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.
With your virtual environment active, install Sphinx into it:
pip install sphinx
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.pydirectly indocs/and puts built files indocs/_build/, which is what the rest of these instructions assume. (Answeringyisn’t wrong, but then your paths will bedocs/source/conf.pyanddocs/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.
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
Replace the placeholder content of
docs/index.rstwith what you already wrote forREADME.rst.Warning
Keep the
.. toctree::block thatsphinx-quickstartput 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.Build it and look at the result. From inside the
docsfolder:.\make.bat html # Windows
make html # macOS/Linux
How do you know it worked? The last line says
build succeeded.Open the generateddocs/_build/html/index.htmlto 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:
Open your project on
git.tu-berlin.de.In the left sidebar, click Settings → General.
Expand the Visibility, project features, permissions section.
Under Project Visibility, choose Public.
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.
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¶
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.Click your username (upper right) → My Projects → Import a Project → Import Manually.
Fill in a name and your repository’s URL (
https://git.tu-berlin.de/...), then click Next.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:
On your RTD project page, click Admin → Integrations (left sidebar) → Add integration.
Choose GitLab incoming webhook from the dropdown and click Add integration.
Copy the URL it shows you (it starts with
readthedocs.org/api/v2/webhook/...).Back on
git.tu-berlin.de, open your project → Settings → Webhooks.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.
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
defline, 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 """ ...
Enable the autodoc extension. Open
docs/conf.py—sphinx-quickstartwrote an emptyextensions = []list; change that existing line to:extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
Both ship with Sphinx, so there’s nothing extra to install.
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_namewith the actual name you chose when generating the project — the dotted path ispackage.module.function, mirroring how you’d import it in Python.Add the new page to the
toctreeindocs/index.rstso it’s reachable, using the filename without its extension:.. toctree:: :maxdepth: 2 processing
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 — runpip install -e .with your virtual environment active. If you seedocument 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.