Part 3 Tasks

As before, create a separate branch and merge request for each sub-task.

Task 0: Create a new repository

Create a fresh, empty project on GitLab and generate a practice package into it, exactly as in Part 1 Tasks Task 1 (remember to untick “Initialize repository with a README”), only the template URL differs:

cookiecutter https://github.com/spirousschuh/cookiecutter-git-workshop-documentation

Then connect it to GitLab, create and activate a virtual environment, and install the package with pip install -e .. See Prerequisites if you need a refresher on any of those steps, or Troubleshooting if something errors.

Task 1: README

Write README.rst in reStructuredText. It should contain:

  • the repository’s purpose

  • an installation guide

  • a small snippet showing how to use the command line interface

The file already exists with placeholder text — replace it. A minimal skeleton to start from:

My Package
==========

What this package does, in a sentence or two.

Installation
------------

.. code-block:: none

   pip install -e .

Two reStructuredText rules that catch everyone out at first: the row of = or - underlining a heading must be at least as long as the heading text, and blank lines are what separate blocks from each other (indentation inside a block must line up too — 3 spaces is the convention).

How do you know it worked? Once merged, GitLab renders it on your project’s landing page. PyCharm can also preview it: open the file and click the preview icon in the top-right of the editor.

Task 2: Create the Sphinx documentation

This generated package doesn’t come with a docs/ folder — you’re setting one up from scratch, just like a real new project would.

  1. With your virtual environment active, install Sphinx into it:

    pip install sphinx
    
  2. Create the folder and run Sphinx’s setup wizard inside it:

    mkdir docs
    cd docs
    sphinx-quickstart
    

    It asks a handful of questions. The answers that matter:

    • “Separate source and build directories (y/n)” — answer n. This keeps conf.py directly in docs/ and puts built files in docs/_build/, which is what the rest of these instructions assume. (Answering y isn’t wrong, but then your paths will be docs/source/conf.py and docs/build/html/ throughout.)

    • Project name, author name, project release — your own values; they appear on the rendered site.

    • Project language — press Enter for English.

    For more background, see Read the Docs’ Sphinx quick-start guide.

  3. Add the docs folder to git:

    Every new file or directory that you create always needs to be added to git if you want to track its history.

    git add docs
    
  4. Replace the placeholder content of docs/index.rst with what you already wrote for README.rst.

    Warning

    Keep the .. toctree:: block that sphinx-quickstart put there — write your text above or below it, but don’t delete it. It’s what links additional pages into the site, and Task 4 needs it.

  5. Build it and look at the result. From inside the docs folder:

    .\make.bat html          # Windows
    
    make html                # macOS/Linux
    

    How do you know it worked? The last line says build succeeded. Open the generated docs/_build/html/index.html to view it — the easiest way is to right-click it in PyCharm’s project tree and choose Open In → Browser.

Task 3: Publish to Read the Docs

Make your repository public

Read the Docs can only build repositories it’s allowed to read:

  1. Open your project on git.tu-berlin.de.

  2. In the left sidebar, click Settings → General.

  3. Expand the Visibility, project features, permissions section.

  4. Under Project Visibility, choose Public.

  5. Scroll down and click Save changes.

Add the build configuration

Add a .readthedocs.yaml file at your repository root (next to pyproject.toml, not inside docs/), so the build is configured reproducibly rather than by hand through the RTD web UI. See Prerequisites for how to create a dot-file safely.

.readthedocs.yaml
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

sphinx:
  configuration: docs/conf.py

python:
  install:
    - method: pip
      path: .

Important

The python: install: block at the end is what makes Read the Docs install your package before building. Without it Task 4 will fail on RTD (though it still works locally) with autodoc: failed to import function, because Sphinx can’t import code that was never installed.

YAML is indentation-sensitive: use spaces, never tabs (a tab is a syntax error), and keep the nesting exactly as shown. Commit and push this file — RTD reads it from your repository, so it must be on the server.

Import the project and build

  1. Create an account at readthedocs.org and log in.

    Note

    RTD offers to connect to GitHub/GitLab.com accounts, but it cannot reach TU Berlin’s self-hosted git.tu-berlin.de. Sign up with an email address instead and use the manual import below.

  2. Click your username (upper right) → My Projects → Import a Project → Import Manually.

  3. Fill in a name and your repository’s URL (https://git.tu-berlin.de/...), then click Next.

  4. On your project page, click Build Version and wait for it to finish.

How do you know it worked? The build turns green, and the View Docs button opens your rendered documentation. If it fails, open the build log — it names the file and line that caused the problem.

Set up automatic rebuilds

Right now RTD only rebuilds when you click the button. A webhook makes your push trigger it automatically — the continuous deployment idea from Part 3: Documentation:

  1. On your RTD project page, click Admin → Integrations (left sidebar) → Add integration.

  2. Choose GitLab incoming webhook from the dropdown and click Add integration.

  3. Copy the URL it shows you (it starts with readthedocs.org/api/v2/webhook/...).

  4. Back on git.tu-berlin.de, open your project → Settings → Webhooks.

  5. Paste the URL into the URL field and click Add webhook.

How do you know it worked? Push a small change to main, then watch your RTD project’s Builds page — a new build should start on its own within a minute or so. If nothing happens, see Troubleshooting.

Task 4: Docstrings

Recall invert_image from Part 2 — it’s in this package too, in the inner package folder as processing.py.

  1. Write a proper docstring for it, following the “Docstrings and autodoc” section of Part 3: Documentation. It goes inside the function, as the very first thing after the def line, indented to match the function body:

    def invert_image(image):
        """
        Invert the colors of an image.
    
        :param image: the image to invert
        :type image:  PIL.Image.Image
        :return:      a new image with inverted colors
        :rtype:       PIL.Image.Image
        """
        ...
    
  2. Enable the autodoc extension. Open docs/conf.py — sphinx-quickstart wrote an empty extensions = [] list; change that existing line to:

    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
    

    Both ship with Sphinx, so there’s nothing extra to install.

  3. Create a new page, e.g. docs/processing.rst, describing the image-inversion process, and pull your docstring into it:

    Image processing
    ================
    
    Some prose explaining what this module is for.
    
    .. autofunction:: your_package_name.processing.invert_image
    

    Replace your_package_name with the actual name you chose when generating the project — the dotted path is package.module.function, mirroring how you’d import it in Python.

  4. Add the new page to the toctree in docs/index.rst so it’s reachable, using the filename without its extension:

    .. toctree::
       :maxdepth: 2
    
       processing
    
  5. Rebuild the docs and confirm your docstring appears, formatted, on the new page.

    If you see WARNING: autodoc: failed to import function '...', the package isn’t installed in the environment you’re building from — run pip install -e . with your virtual environment active. If you see document isn't included in any toctree, you skipped the previous step. Both are in Troubleshooting.

You now have a documented, publicly-published package. Move on to Part 4: Python Packaging to make it properly installable and distributable too.