This is a template I use to create projects and docs. This page is to give a special emphasis on docs. I’ll be creating a project named FeatMF.

Table of contents

Pre-requisites

You must have the following

  • A github account. I prefer to have SSH keys and gh CLI setup.
  • A readthedocs account with GitHub (or other platforms) connected.
  • For environment management, you have pyenv and Python poetry installed.
  • Knowledge of git, bash, python environments, documentation. Some reference is included below.

Steps

Do the following

Step 1: Setup the empty repository locally

mkdir FeatMF && cd $_
git init -b main
touch README.rst

Add other things like IDE files, .gitignore files, etc. We’ll choose the GNU LGPL v3 license.

Add the first commit

git add --all
git commit -m "First commit"

Step 2: Upload the repository to GitHub

  • On GitHub (or any git hosting platform), create repository with no README or LICENSE (everything will be uploaded from local).

  • Add remote

      git remote add origin https://github.com/TheProjectsGuy/FeatMF.git

  • Push the changes to GitHub

      git push origin -u main

Step 3: Setup Python Poetry

  1. Setup Python poetry for this project (using Python from pyenv)

    • Initialize it (an interactive menu setup follows)

        poetry init

      I choose python 3.8 for this project (supported by multiple libraries), but my OS has python 3.10.6. I do not prefer using the system interpreter (unless it’s absolutely necessary)

    • We’ll create a pyenv for python 3.8 and make the local folder use that python all the time.

        # Depending on what you have in `~/.zshrc`
  pyenv-init || eval "$(pyenv init -)"
  # Install Python 3.8
  pyenv install 3.8
  pyenv local 3.8
  python --version    # Should be 3.8.*

      I like to use my system python by default, so I have a pyenv-init function in my ~/.zshrc to initialize pyenv (same init command).

    • Make sure poetry uses this Python

        poetry env use python
  # Test that this worked
  poetry shell

  2. Install core libraries through poetry

    In pyproject.toml file, add the dependencies. For now, we’ll just install the latest versions of numpy, scipy, matplotlib, opencv-contrib-python, and PyTorch (version 1.13).

     python = "^3.8.0"
 numpy = "*"
 scipy = "*"
 matplotlib = "*"
 opencv-contrib-python = "*"
 torch = "^1.13"
 torchvision = "*"
 torchaudio = "*"

    Such wildcard entries are better left to the development builds. Make them concrete before releasing this to public. Run the poetry commands to install everything

     poetry install
 poetry update

  3. Show the installed packages as a tree

     poetry show --tree

Step 4: Create Documentation

Create Local Docs

  1. Create entry in the pyproject.toml file

     [tool.poetry.group.docs]
 optional = true

 [tool.poetry.group.docs.dependencies]
 sphinx = ">= 5.2"

    And install everything

     poetry install --with docs

  2. Create folder with basic quickstart

     cd FeatMF
 poetry shell
 sphinx-quickstart docs

    Put the docs/build folder in .gitignore

  3. Build the docs

     sphinx-build -b html docs/source/ docs/build/html

    See the preview in ./docs/build/html/index.html file

Choose a Theme

  1. Install the theme. We’ll use the rtc-theme

    In pyproject.toml add the theme (under the docs group dependencies)

     sphinx-rtd-theme = ">= 1.0"

    Update poetry

     poetry install --with docs
 poetry update

  2. Use that theme

    In ./docs/source/conf.py, add/change the following

     html_theme = 'sphinx_rtd_theme'

    Rebuild the site

     sphinx-build -b html docs/source/ docs/build/html

Deploy

Deploy on readthedocs.org

  1. Push all the latest changes to remote (GitHub)
  2. Import project and reach the dashboard.
  3. Choose the repository in the list.

Recommendations

  • For (offline) reference, you can optionally save the entire theme (source)

      cd /scratch
  wget --recursive --no-parent https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/

References