Prerequisite:
In this guide you need a GitHub account and an existing repository!
Learn about python docstrings!

  1. Clone the repository to your local system
  2. Open a terminal in the root path of the local repository.
  3. Do ‘mkdir sphinx’
  4. Do ‘cd sphinx’
  5. Do ‘pip install sphinx’
  6. Do ‘pip install recommonmark’
  7. Do ‘pip install python-docs-theme-technopathy’
  8. Do sphinx-quickstart --ext-autodoc --ext-githubpages --extensions recommonmark
    1. “Separate source and build directories (y/n) [n]: y”
    2. Answer questions about your project!
  9. Edit ‘./source/conf.py’:
    import os
    import sys
    sys.path.insert(0, os.path.abspath('../..'))

    and
    html_theme = 'python_docs_theme_technopathy'
    html_context = {'github_user_name': 'your_username', 'github_repo_name': 'your_repository','project_name': project}
  10. Do ‘sphinx-apidoc -f -o source/ ../your-package/’
  11. To link the README.md and LICENSE file of the repository to the docs
    1. Do ‘cd source’
    2. Do ‘ln -s ../../README.md’
    3. Do ‘ln -s ../../LICENSE copyright.rst’
    4. Edit ‘../../LICENSE’ and underline the first line with equal signs
    5. Do ‘cd ..’
    6. Edit ‘./source/index.rst’:
      1. Add ‘Readme <README.md>’ and ‘Copyright <copyright.rst>’ exactly this way:
  12. Now create the HTML files with:
    make html
    (If you have troubles, use ‘make html -d’ to activate the debug mode and get infos about the reason.)
  13. Watch the generated files:
    firefox build/html/index.html
  14. If the HTML files are fine, copy them to ‘../docs’:
    mv build/html ../docs
  15. To avoid a 404 error when you open your github pages, you have to create a forward from ‘readme.md’ to ‘index.html’:
    1. Create an empty file in the ‘docs’ folder with the name “readme.md”
    2. Open the new file and paste:
      ---
      permalink: /index.html
      ---
  16. Now you should have a file hierarchy similar to this:
  17. Commit your changes and push them to GitHub!
  18. Open your repository on https://github.com/
  19. Click on “Settings” and scroll down to “GitHub Pages”:
  20. Select the “master branch /docs folder” entry:
  21. Its done! Click on the link that pops up after saving!

To update the documentation, just go into your ‘sphinx’ folder in your local repository and do ‘make html’ again. Control the new files, copy them to the ‘docs’ folder and push it to GitHub.

If you like to use an other template, here are some: https://sphinx-themes.org/