If you would like to suggest an update or addition to the Now I Know My ABCD documentation site, without writing the code yourself, first navigate to the website page you'd like to suggest a change to. Then, open a GitHub issue using the "open issue" link in the GitHub drop-down menu at the top of the page. Include a comment with your issue describing your suggested change, and a site moderator will review your issue and update the website.
If you have more general ABCD questions, please visit the Discussion Board! Opening a GitHub issue is best suited to targeted content update requests and suggestions for individual pages.
The first step to contributing to the Now I Know My ABCD docs is to fork the GitHub repository containing the source code. In your local fork, you can write new website content or edit existing content at your own pace without affecting the main site.
Once you're ready, open a pull request. A site moderator will review your pull request and work with you to make sure any tutorial code is reproducible. Once the updates are finalized, they will merge your updates into the main site!
If you would like to propose a new tutorial page for addition to the Now I Know My ABCD docs, these instructions will help you get started. They are written for contributors who already feel comfortable with Python, Jupyter, and Markdown.
All new pages go into the docs subfolder. Text-only pages can be written in Markdown, while pages with code can be written as Jupyter notebooks. (Eventually, code pages can also be written in R Markdown, but I haven't figured out how to do that yet.)
The table of contents is declared in _toc.yml in the project root folder. Add a page to the table of contents by adding a new line with - file: and then your page filename, not the page title with no file ending. JupyterBook will automatically render the page's internal title (the level-1 header at the beginning of the page) as the chapter name in the table of contents.
Order matters! Add the new line where you want the resulting chapter to end up.
The website is currently equipped with a GitHub Actions workflow that renders the web-hosted version of the site every time a change is pushed on the main branch. You do not need to have jupyter-book installed on your local machine in order to get the live website to update! 🎉 :tada:
However, you do need to have it installed if you want to preview website edits before pushing. This repo comes with a conda environment.yml file that you can (theoretically) use to install all relevant packages. In Monica's experience, environment.yml files can be picky and sometimes overly OS-specific, so please contact Monica if you have issues recreating the Python dependencies.
When you have JupyterBook set up, the following terminal command will render the book locally when run from the project root folder:
jupyter-book build docs/The local book homepage should then be accessible at docs/_build/html/index.html in your browser window.