Updated readme

README.md

@@ -2,14 +2,77 @@
 
 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`
+## 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```
+
+```pip install ghp-import```
+
+Installation instructions:
+1. Clone the directory ````git clone [email protected]: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 installed, run ```ope```, if it is insalled, a list of ope commands should print on your terminal
+
+How to create a new project:
+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 and edit a new book:
+1. Enter back into the terminal and cd into the books folder and the run:
+- ```ope new_book <your-book-name>```
+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: 'Name of section'
+    numbered: true
+    chapters:
+    - file: directory/file
+    sections: 
+    - file: dummy_part/section
+```
+If you don't want your chapters to be numbered, change numbered to false
+
+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 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
+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:
+
+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 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 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