The aim of this repository is to showcase a simple implementation of automatically generated documentation which uses jupyter-books (build) and github pages (deploy). -> like this one

check the docker image here

• A template to build documentation from any python code automatically 2
  • Mind Map
• Getting started
  • 1. Create a repository
  • 2. Add documentation
  • 3. Configure the documentation
  • 4. Build the documentation
  • 5. Add Github action for deployment
  • 6. Test the progress so far
  • 7. Add python code and modules
  • 8. Install the code
  • 9. Update building script
  • 10. Test your page
• Now you can add and modify your documentation and at any push it will be updated automatically!

create a repository or go to the repository you want to add documentation.

• Create a folder in your repository called /docs where you'll host your documentation.

• Add in the /docs folder the markdown files for your documentation

• Create a _toc.yml file to setup your documentation table of content (see a more in depth guide here)
  as an example here's some code:

    - file: index
      numbered: true
  
    - part: Introduction
      chapters:
        - file: intro/intro1
        - file: intro/intro2
        - file: intro/test.ipynb
  
    - part: Core Code
      chapters:
        - file: core/main1
        - file: core/main2
  
    - part: API
      chapters:
        - file: api/index

  You can skip the manual setup of the _toc.yml file by running the following code:

      jupyter-book toc ./docs
  

  and then modify the structure to your taste You can add any jupyter notebook as a documentation page like this:

  - file: intro/your_notebook.ipynb

• add a requirements.txt file ( inside /docs) with the following dependencies:

      jupyter-book
      jupytext
      sphinx_autodoc_typehints
  

• create a folder /api inside /docs and create (inside) a file index.rst:

      .. _api:
  
      API Reference
      =============
  
      Information on specific functions, classes, and methods.
  
  
      Modules
      -------
  
      For the average user's workflows.
  
      .. autosummary::
      :toctree:
      :recursive:
  
      numpy.sum
  

  where numpy.sum is just to show a working implementation.

• Create a _config.yml file where to setup your page configuration (see a more in depth guide here)
  It's important to insert the right extension in order to build the documentation correctly, here's an example:

  sphinx:
  extra_extensions: - sphinx.ext.viewcode - sphinx.ext.napoleon - sphinx.ext.autodoc - sphinx_autodoc_typehints - sphinx.ext.autosummary - sphinx.ext.intersphinx
  
          config:
              autosummary_generate: True
              autosummary_imported_members: True
              intersphinx_mapping:
                  python:
                      - "https://docs.python.org/3"
                      - null
                  numpy:
                      - "https://docs.scipy.org/doc/numpy/"
                      - null
      ```
      where `intersphinx_mapping` allows the build to get the documentation online for the specified packages (i.e. `numpy`).

• Write a make file to build the documentation:

      .PHONY: docs
  
      docs:
          rm -rf docs/_build/html
          find docs/api ! -name 'index.rst' -type f -exec rm -f {} +
          pip install -qr docs/requirements.txt
          jb build docs

At this point the structure of the folder is ready to go, we can then move on to setup an action which will build and upload the documentation automatically.

• Create a .github/workflows/ folder

• Add in the folder a .yml file for your action:

      name: page_deploy
  
      on: push
      # Trigger the workflow on push or pull request,
      # but only for the main branch
      # push:
      #   branches:
      #     - main
  
      jobs:
      deploy-book:
          runs-on: ubuntu-latest
          steps:
          - uses: actions/checkout@v3
  
          # Install dependencies
          - name: Set up Python
          uses: actions/setup-python@v4
          with:
              python-version: "3.8"
  
          - name: Install dependencies
          run: |
              python -m pip install --upgrade pip
              pip install -r requirements.txt
          # Build the book
          - name: Build the book
          run: |
              make docs
          # Push the book's HTML to github-pages
          - name: GitHub Pages action
          uses: peaceiris/actions-gh-pages@v3
          with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: ./docs/_build/html
  

• To reuse this code you may need to change a couple of lines:

  • if your docs files are in the source folder as suggested in this guide you don't have to change the path for the build and publish. If this is not the case you need to change the folling lines:

        #change with the path to your files
        run: |
            jupyter-book build ./docs

        #change with the path to your files
            publish_dir: ./docs/_build/html

• If you decide to reuse this code, remember also to add a requirements.txt in the main repository for the dependencies of your code.

Note: you don't need to initiate gh-pages branch or abilitate your repo.

• Commit and push the changes, check in the settings of your github repository if the link to your documentation has been activated correcly
• check the github actions section of your repository and check whether there's any fail
• If everything went smoothly, then go to the settings and scroll down to github pages -> click on the link and see if your documentation is up

• create another folder to hold the code of your package and make sure you insert an __init__.py file for each module.
• to get better autogenerated descriptions of your code add docstrings for each function and suggest the appropriate type for the inpute variables in this way:

      def difference(a: int, b: int):
          """
          Subtracts two integers
          """
          return a-b

• to make the code intall-able we need to create a setup.py file in the main repository:

      setup(
          name='myproject',
          description='a template for making documentation',
          long_description=long_description,
          long_description_content_type='text/markdown',
          version='0.2',
          author='your name',
          author_email='youremail',
          url='https://github.com/fedem-p/my_documentation_template',
          packages=find_packages(),
          include_package_data=True,
          python_requires=">=3.7",
          license='MIT',
          zip_safe=False,
          entry_points={
              'console_scripts': ['myproject=myproject.entry_points:main'],
          },
          classifiers=[
              'Intended Audience :: Developers',
              'Programming Language :: Python :: 3.7',
              'Natural Language :: English',
          ],
          keywords='auto documentation'
      )

  for a more in-depth guide check this documentation

• Now test your code by running

            pip install -e .
  

  from within the repository.

• if it install everything without errors you can further test that everything worked properly in this way:\

  • run python, import sys and run sys.path -> your repository should be in the list
  • run python, import your package and some modules -> if you get any errors you may need to check if the code runs properly

The last step is to update a couple of files:

• Change the make file in this way:

      .PHONY: docs
  
      docs:
          rm -rf docs/_build/html
          find docs/api ! -name 'index.rst' -type f -exec rm -f {} +
          pip install -qr docs/requirements.txt
          pip install -r requirements.txt     ## new line
          pip install -e .                    ## new line
          jb build docs

• add to the index.rst file the modules that you want to reference:

  For the average user's workflows.
  
      .. autosummary::
      :toctree:
      :recursive:
  
      numpy.sum
      myproject
      myproject.module
  

  for a great example of this you can check the napari repository

Finally you can commit your changes and see if your documentation gets build properly. Repeat the same steps as in section number 6 and navigate to the api page. Check if there are the links to your modules and functions.