From d62e367d7d77b2a02d84511651b8decc307cce66 Mon Sep 17 00:00:00 2001 From: meera malhotra Date: Fri, 31 May 2024 15:00:09 -0400 Subject: [PATCH 1/2] added installation and book editing instructions to the read me --- README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c1d6166..acc1a30 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,87 @@ This tool is designed to facilitate the management of projects within the Open Publishing Environment (OPE). It includes a variety of functions for handling repositories, books, containers, and course creation. ## Installation - -1. Clone this repository to your local machine. -2. Ensure you have Git installed, as it is required for several functions. -3. **Command**: In the directory, run `./install.sh` +Before you install the ope tool and create your own open source textbook with the tool, make sure you have the dependencies you need by running: + +```pip install jupyter-book``` + +```pip install ghp-import``` + +Installation instructions: +1. On your device, create a directory +- To do this run the command: ```mkdir ``` where example name is what you want to name your directory +2. When you’re in the directory run the command: ```git clone git@github.com:OPEFFORT/tools.git``` +3. Then cd into the tools directory tools +- You can run the command: ```cd tools``` +4. Run the command: ```./install.sh``` +- Post-installation instructions should print +- Run the first command in the post installation instructions: it should look something like this: ```export PATH=/home/your-laptop-name/txt/tools/bin:$PATH``` + +Your environment should be set up, and you can use the ope tool to create your project. To test if the ope is installled, run ```ope```, if it is insalled, a list of ope commands should print on your terminal + +How to create a new project: +1. Outside of the terminal, make a new github repository +2. Copy the ssh link that you usually would make usually use for git clone to clipboard, it should look like this: ```git@github.com:github-username/repo.git``` +- Make sure you use the ssh link, and not the http +3. Then use the ope new_project command with the link you copied, it should look like: ```ope new_project [git@github.com:github-username/repo.git]``` +- The repo is an optional argument, if you would like to add it later on, use the ```ope repo_add``` command later +4. Move out of tools and back into the root directory, if you are not already in the root directory +5. If you exit the terminal, and refresh your github repository, the repository should be populated with tools for your first ope book + +You have now created your first project, and can create a new textbook + +How to create a new book: +1. Enter back into the terminal, and cd into the books folder +2. Once you are in the books folder, use the ope new_book command to create a new textbook, run: +- ```ope new_book ``` +3. Once you are in books, you can work on editing the content +4. cd into your new book, and cd into the content folder + +Editing your new book: +1. While you are in the content folder, open up a text editor, and go to the your-text-book-name_config.yml file +2. Edit the title to be your book name as well as the name and copyright year +3. Under repository, change the url to be relevant to your textbook as well, keeping github at the beginning +- It should look like: https://github.com/yourname/relevant-textbook-phrase +4. Then open up the your-text-book-name_intro.md file +5. This file will be your books introduction, edit it to populate your landing page +6. Open up your-text-book-name_toc.yml this file will contain your intended structure for your textbook +7. To add chapters or sections to this book, add the text under this line, under parts, where each file or section is the path to the chapter content +``` +- caption: 'Chapter 1' + numbered: true + chapters: + - file: introduction/intro/chapter1 + - file: introduction/intro/chapter2 + sections: + - file: introduction/intro/section1 +``` +You can change numbered to false, if you don't want your chapters to be numbered + +8. To have content where that chapter will be, create a folder in the content folder, following the path you wrote in the previous step + - For example, if I placed a chapter in introduction/intro/chapter1, in content I would create a directory introduction, and within that directory create another directory, intro. Within intro I would make a file called chapter1.ipynb + - Remember to add the .ipynb, even though the path you wrote in the tock.yml file does not include it + - If you need a sample .ipynb file, you can look at or even copy the what's in the dummy file as a template +9. Continue this process until your textbook structure is layed out and your folders are populated with the corresponding .ipynb's +10. To see what your textbook looks like, go into the books folder and run ```ope build``` and copy and paste the provided link in your browser + - If you are having issue using the command, ensure that you are in a folder with the Makefile + + +Publishing your textbook: + +11. While in the books folder with the Makefile, which should share the title of your book, run ```ope pub``` +12. You can now check github, where a second branch called gh-pages, for github pages, should be published +13. Check the actions tab, and wait until your textbook is deployed +14. Go to settings, and then github pages, then click on the link where it says your site is live +15. Once you are on the site, it will give you a 404 error, do not worry, that's normal, just add your book's name at the end of the url, and your textbook will be hosted +16. Your book should be published and accessible by anyone! + + +Common issues: +- If you're getting issues with Make, make sure you are running ope build and ope pub in the folder with the Makefile +- If you're unable to use ope tools, cd back into tools, and reset your path by following the instructions and copy and pasting the export PATH line +- If nothing is appearing on your site, make sure your .ipynbs have titles + +If you have any other questions or need additional help in the process: checkout https://www.youtube.com/watch?v=-_0HD_oAK5o&list=LL ## Usage From 99c299492734a41b296f27f8d0b1d9d11b845bd6 Mon Sep 17 00:00:00 2001 From: meera malhotra Date: Thu, 13 Jun 2024 10:36:54 -0400 Subject: [PATCH 2/2] updated readme --- README.md | 92 +++++++++++++++++++++++-------------------------------- 1 file changed, 39 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index acc1a30..8bfc3ea 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This tool is designed to facilitate the management of projects within the Open Publishing Environment (OPE). It includes a variety of functions for handling repositories, books, containers, and course creation. -## Installation +## User Guide Before you install the ope tool and create your own open source textbook with the tool, make sure you have the dependencies you need by running: ```pip install jupyter-book``` @@ -10,83 +10,69 @@ Before you install the ope tool and create your own open source textbook with th ```pip install ghp-import``` Installation instructions: -1. On your device, create a directory -- To do this run the command: ```mkdir ``` where example name is what you want to name your directory -2. When you’re in the directory run the command: ```git clone git@github.com:OPEFFORT/tools.git``` -3. Then cd into the tools directory tools -- You can run the command: ```cd tools``` -4. Run the command: ```./install.sh``` -- Post-installation instructions should print -- Run the first command in the post installation instructions: it should look something like this: ```export PATH=/home/your-laptop-name/txt/tools/bin:$PATH``` +1. Clone the directory ````git clone git@github.com:OPEFFORT/tools.git``` +2. Run the command: ```./install.sh``` -Your environment should be set up, and you can use the ope tool to create your project. To test if the ope is installled, run ```ope```, if it is insalled, a list of ope commands should print on your terminal +Your environment should be set up, and you can use the ope tool to create your project. +To test if the ope is installed, run ```ope```, if it is insalled, a list of ope commands should print on your terminal How to create a new project: -1. Outside of the terminal, make a new github repository -2. Copy the ssh link that you usually would make usually use for git clone to clipboard, it should look like this: ```git@github.com:github-username/repo.git``` -- Make sure you use the ssh link, and not the http -3. Then use the ope new_project command with the link you copied, it should look like: ```ope new_project [git@github.com:github-username/repo.git]``` -- The repo is an optional argument, if you would like to add it later on, use the ```ope repo_add``` command later -4. Move out of tools and back into the root directory, if you are not already in the root directory -5. If you exit the terminal, and refresh your github repository, the repository should be populated with tools for your first ope book +1. Create a new github repository from the web UI +2. In the terminal, run ope new_project [repo-url]. +- The repo-url is an optional argument, if you would like to add it later on, use the ope repo_add command later +3. Refresh your github repository from the Web UI, the repository should be populated with tools for your first ope book You have now created your first project, and can create a new textbook -How to create a new book: -1. Enter back into the terminal, and cd into the books folder -2. Once you are in the books folder, use the ope new_book command to create a new textbook, run: +How to create and edit a new book: +1. Enter back into the terminal and cd into the books folder and the run: - ```ope new_book ``` -3. Once you are in books, you can work on editing the content -4. cd into your new book, and cd into the content folder - -Editing your new book: -1. While you are in the content folder, open up a text editor, and go to the your-text-book-name_config.yml file -2. Edit the title to be your book name as well as the name and copyright year -3. Under repository, change the url to be relevant to your textbook as well, keeping github at the beginning -- It should look like: https://github.com/yourname/relevant-textbook-phrase -4. Then open up the your-text-book-name_intro.md file -5. This file will be your books introduction, edit it to populate your landing page -6. Open up your-text-book-name_toc.yml this file will contain your intended structure for your textbook -7. To add chapters or sections to this book, add the text under this line, under parts, where each file or section is the path to the chapter content +2. Your book is now made, cd into the content folder, once in the content folder, +three files must be modified: +3. your-text-book-name_config.yml file +- edit the title, name, url (keeping github at the root and replacing joyvan) and copyright year +4. your-text-book-name_intro.md file +- this file will be your books introduction, edit it to populate your landing page +5. your-text-book-name_toc.yml, this file will contain your intended structure for your textbook +6. To add chapters or sections to this book, add the text under this line, under parts, where each file or section is the path to the chapter content ``` -- caption: 'Chapter 1' - numbered: true - chapters: - - file: introduction/intro/chapter1 - - file: introduction/intro/chapter2 - sections: - - file: introduction/intro/section1 + - caption: 'Name of section' + numbered: true + chapters: + - file: directory/file + sections: + - file: dummy_part/section ``` -You can change numbered to false, if you don't want your chapters to be numbered +If you don't want your chapters to be numbered, change numbered to false -8. To have content where that chapter will be, create a folder in the content folder, following the path you wrote in the previous step +7. To have content where that chapter will be, create a folder in the content folder, following the path you wrote in the previous step - For example, if I placed a chapter in introduction/intro/chapter1, in content I would create a directory introduction, and within that directory create another directory, intro. Within intro I would make a file called chapter1.ipynb - - Remember to add the .ipynb, even though the path you wrote in the tock.yml file does not include it + - Remember to add the .ipynb, even though the path you wrote in the toc.yml file does not include it - If you need a sample .ipynb file, you can look at or even copy the what's in the dummy file as a template -9. Continue this process until your textbook structure is layed out and your folders are populated with the corresponding .ipynb's -10. To see what your textbook looks like, go into the books folder and run ```ope build``` and copy and paste the provided link in your browser +8. Continue this process until your textbook structure is layed out and your folders are populated with the corresponding .ipynb's +9. To see what your textbook looks like, go into the books folder and run ```ope build``` and copy and paste the provided link in your browser - If you are having issue using the command, ensure that you are in a folder with the Makefile Publishing your textbook: -11. While in the books folder with the Makefile, which should share the title of your book, run ```ope pub``` -12. You can now check github, where a second branch called gh-pages, for github pages, should be published -13. Check the actions tab, and wait until your textbook is deployed -14. Go to settings, and then github pages, then click on the link where it says your site is live -15. Once you are on the site, it will give you a 404 error, do not worry, that's normal, just add your book's name at the end of the url, and your textbook will be hosted -16. Your book should be published and accessible by anyone! +1. While in the books folder with the Makefile, which should share the title of your book, run ```ope pub``` +2. You can now check github, where a second branch called gh-pages, for github pages, should be published +3. Check the actions tab, and wait until your textbook is deployed +4. Go to settings, and then under pages, then click on the link where it says your site is live +5. Once you are on the site, it will give you a 404 error, do not worry, that's normal, just add your book's name at the end of the url, and your textbook will be hosted. Now your book should be published and accessible by anyone! -Common issues: + +Common mistakes: - If you're getting issues with Make, make sure you are running ope build and ope pub in the folder with the Makefile -- If you're unable to use ope tools, cd back into tools, and reset your path by following the instructions and copy and pasting the export PATH line - If nothing is appearing on your site, make sure your .ipynbs have titles +- If there are issues with what's being pushed to github, make sure you're running the ope commands in the correct directories +- If you get resource authorization issues, make sure you're logged into docker before running ```make push```, you can use the ```docker login quay.io``` command to login If you have any other questions or need additional help in the process: checkout https://www.youtube.com/watch?v=-_0HD_oAK5o&list=LL ## Usage - Each function in the script is intended for specific tasks. Below are the usages and descriptions for each function. ### General