Task: Make a documentation website for a project

Okay. You have a project. You want to make a webpage and a documentation. Here is one way to do it.

For the webpage, you can use the GitHub Pages service. For creating the documentation, you can use SphinX which autogenerates a documentation from the docstrings.

Result

Check the documentation page for my tflow project.

Making a simple website with Github Pages

Github pages provides a simple way to make a website using Markdown.

With a pre-existing repository,

1. On Terminal, cd to your repository.
2. Create a branch in your repo for your GitHub Page: git checkout -b gh-pages
3. Create a markdown file called index.md.
4. Push it to GitHub by using git push origin gh-pages
   Tips: Making a website may take a few minutes to complete. Make sure to clear cache when you renew the webpage.

It is not a bad idea to separate a repo about the project webpage and the documentation.

References:

• Making a simple website with Markdown
  
• Project Documentation with GitHub Pages

Making a code documentation webpage using SphinX

To do this, you need to install SphinX.

1. Install SphinX: pip install sphinx
2. cd your_project_directory
3. sphinx-quickstart docs… This makes a directory called docs and files like a conf.py.
4. If you are using numpy or Google style docstrings, you must enable napoleon in the Sphinx conf.py:
   … You can specify the SphinX theme in conf.py like html_theme = "sphinx_book_theme"
   … For my project, I decided to use a third-party theme sphinx_book_theme which you can install using pip install sphinx-book-theme.
   See Sphinx Book Theme for more details.

   # conf.py
   
   # Add napoleon to the extensions list
   extensions = ['sphinx.ext.napoleon']
   # Specify the theme
   html_theme = "sphinx_book_theme"

1. Build your API documentation: sphinx-apidoc -f -o docs/source your_project_directory
   … -f: overwrite existing files, -o: output directory
2. Edit your index.rst file
   … This will be the main page of your documentation.
   … The format is reStructuredText. Quick reference
3. Generate html files: make html
   This should create a directory called doctrees and build.
4. GitHub recognizes your_project_directory/index.md as a default project website. Change this. … Go to your repo webpage on GitHub, go to “Settings”->”Pages”, and set source to “gh-pages/docs” … GitHub Pages uses Jekyll as a default tool to make a website. You must disable it by creating an empty file called your_project_directory/docs/.nojekyll
5. Commit and push the changes.

When you update the documentation, repeat Steps 5-9 except Step 8.

References:

Step1-3: Sphinx Quickstart Step4: Sphinx Google Style