Updated readme #5
Conversation
|
This is the most comprehensive ope doc I've ever seen! Thanks for the effort! I left some inline comments. Also can you squash your 3 commits into 1? Here is an example: https://www.freecodecamp.org/news/git-squash-commits/ |
README.md
Outdated
|
|
||
| ```pip install ghp-import``` | ||
|
|
||
| You will also need docker **and** an account with docker, more instructions on downloading docker are here, if you don't yet have it: https://docs.docker.com/desktop/ |
There was a problem hiding this comment.
I think this part could be moved to the container building instructions somewhere else.
README.md
Outdated
| 1. On your device, create a directory | ||
| - To do this run the command: ```mkdir <example-name>``` where example name is what you want to name your directory | ||
| 2. When you’re in the directory, run the command: ```git clone [email protected]:OPEFFORT/tools.git``` | ||
| 3. Then cd into the tools directory tools |
There was a problem hiding this comment.
I think steps 1-3 are too detailed. We just need to keep step 4 and start from there.
README.md
Outdated
| - 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``` |
There was a problem hiding this comment.
In the new install.sh, is it changed to write the path to .bashrc?
There was a problem hiding this comment.
yes! getting rid of in the install instructions
README.md
Outdated
| - 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 |
README.md
Outdated
| 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 |
There was a problem hiding this comment.
I think steps 1-6 could be as simple as: 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. 4. Refresh your github repository from the Web UI, the repository should be populated with tools for your first ope book
README.md
Outdated
| 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 |
There was a problem hiding this comment.
Just combine 1-4 into 1 step:
How to create a new book:
cd into your-project-name/books directory, run ope new_book <your-book-name> to create a new textbook.
Editing your new book:
- cd into your new book's content directory to edit the content
- ....
README.md
Outdated
| 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: |
There was a problem hiding this comment.
Since there are too many steps for editing the content, we could categorize by files such as:
Three files need to be modifies:
-
your-text-book-name_config.yml: Edit the title to be your book name xxxx
-
your-text-book-name_intro.md: xxx
-
your-text-book-name_toc.yml: add your step 6, 7, 8 here
README.md
Outdated
| 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 | ||
| 6. Your book should be published and accessible by anyone! | ||
|
|
||
| Containerization: |
There was a problem hiding this comment.
I think we could put it into container-template repo readme file
README.md
Outdated
| 3. Once you've selected slide types, your container image can be rendered as a presentation, using the slides icon on the top right corner | ||
| 4. Click through and see your slide show! | ||
|
|
||
| Publishing the container image: |
|
here is my version of readme: https://github.com/DanNiESh/tools-meera/blob/updated-readme/README.md. I modified the lists, steps and some other stuff to make it more readable in markdown format. Let me you what you think. |
|
Hi Danni!
The updated README looks really good! It's way more readable now, I was
just wondering if we could get rid of one line- under common mistakes, the
line that says:
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
I think I had added that for the container common problems, so I can add it
to the readme for the container repo, rather than the tools repo
…-Meera
On Tue, Jun 25, 2024 at 3:55 PM Danni Shi ***@***.***> wrote:
here is my version of readme:
https://github.com/DanNiESh/tools-meera/blob/updated-readme/README.md. I
modified the lists, steps and some other stuff to make it more readable in
markdown format. Let me you what you think.
—
Reply to this email directly, view it on GitHub
<#5 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/BIUO65IOQVC2OIFMYWDX7HDZJHDKNAVCNFSM6AAAAABIXEDE36VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCOBZHA2TKOJZGU>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
Oh! I also think we should add an exec bash command to the instructions,
right after ./install.sh, bc the new tool needs bashrc to be reset
…On Tue, Jun 25, 2024 at 4:52 PM Meera Malhotra ***@***.***> wrote:
Hi Danni!
The updated README looks really good! It's way more readable now, I was
just wondering if we could get rid of one line- under common mistakes, the
line that says:
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
I think I had added that for the container common problems, so I can add
it to the readme for the container repo, rather than the tools repo
-Meera
On Tue, Jun 25, 2024 at 3:55 PM Danni Shi ***@***.***>
wrote:
> here is my version of readme:
> https://github.com/DanNiESh/tools-meera/blob/updated-readme/README.md. I
> modified the lists, steps and some other stuff to make it more readable in
> markdown format. Let me you what you think.
>
> —
> Reply to this email directly, view it on GitHub
> <#5 (comment)>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/BIUO65IOQVC2OIFMYWDX7HDZJHDKNAVCNFSM6AAAAABIXEDE36VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCOBZHA2TKOJZGU>
> .
> You are receiving this because you authored the thread.Message ID:
> ***@***.***>
>
|
Now include installation, set up, and containerization instructions, as well as troubleshooting for common errors