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 :doc:`../part1-git-basics/tasks` Task 1 (remember to untick "Initialize repository with a README"), only the template URL differs: .. code-block:: none 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 :doc:`../prerequisites` if you need a refresher on any of those steps, or :doc:`../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: .. code-block:: rst 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: .. code-block:: none pip install sphinx #. Create the folder and run Sphinx's setup wizard inside it: .. code-block:: none 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 `_. #. 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. .. code-block:: none git add docs #. 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. #. Build it and look at the result. From inside the ``docs`` folder: .. code-block:: none .\make.bat html # Windows .. code-block:: none 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: #. 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 :doc:`../prerequisites` for how to create a dot-file safely. .. code-block:: yaml :caption: .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 ______________________________ #. 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 :doc:`index`: #. 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 :doc:`../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 :doc:`index`. It goes **inside** the function, as the very first thing after the ``def`` line, indented to match the function body: .. code-block:: python 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-quickstart`` wrote an empty ``extensions = []`` list; change that existing line to: .. code-block:: python 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: .. code-block:: rst 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. #. Add the new page to the ``toctree`` in ``docs/index.rst`` so it's reachable, using the filename without its extension: .. code-block:: rst .. 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 — 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 :doc:`../troubleshooting`. You now have a documented, publicly-published package. Move on to :doc:`../part4-packaging/index` to make it properly installable and distributable too.