Correct readthedocs.yaml configuration

[jepler]

I recently filed #82 about a broken link in the properdocs documentation to instructions for use with the readthedocs service. However, the proposed configuration in #83 does not work for me: rtd still builds with mkdocs, not properdocs. I wanted to continue the discussion here instead of in #82 or a fresh issue, so that maybe folks in the community can check whether my proposed fix is a good one or is still incomplete/suboptimal.

Here's what I know right now:

My project source, living on branch called "properdocs":
https://codeberg.org/jepler/wwvbpy/src/branch/properdocs

corresponding readthedocs build:
https://app.readthedocs.org/projects/wwvbpy/builds/35341248/

In the log you can see the following main steps called out:

	pip install -r requirements-doc.txt .
	python -m pip install --upgrade --no-cache-dir pip setuptools
	python -m pip install --upgrade --no-cache-dir mkdocs
	cat properdocs.yaml
	python -m mkdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html --config-file properdocs.yaml

The automatic installation of mkdocs by rtd still occurs, and python -m mkdocs build.. is invoking mkdocs. This can be seen in the page metadata of https://wwvbpy.readthedocs.io/en/properdocs/: <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.7"> and in the full rtd build log which contains the familiar "Warning from the Material for MkDocs team" about the future incompatibility of MkDocs 2.0.

Instead, I created a 2nd branch, properdocs-rtd2, and used a readthedocs config that specifically calls out the commands to run, instead of relying on their mkdocs presets:

# SPDX-FileCopyrightText: 2024 Jeff Epler
#
# SPDX-License-Identifier: GPL-3.0-only

version: 2

build:
  os: ubuntu-lts-latest
  tools:
    python: "3"
  jobs:
    install:
      - pip install -r requirements-doc.txt .
    build:
      html:
        - properdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html

This appears to work, https://wwvbpy.readthedocs.io/en/properdocs-rtd2/ reflects <meta name="generator" content="mkdocs-ProperDocs 1.6.7, mkdocs-material-9.7.7">.

[morvayo]

your second configuration matches the documented custom build job approach

the mkdocs preset chooses the MkDocs builder even when its config file is named properdocs.yaml overriding build.jobs.build.html with properdocs build selects the actual command you want

the important detail is that overriding the install job also makes you responsible for installing ProperDocs and its theme and plugins your requirements file needs to contain those

$READTHEDOCS_OUTPUT/html is the correct output directory for the hosted HTML

[jepler]

Do you think my analysis of why the current instructions won't work is accurate? If so, should I submit a doc PR to change the documentation to reflect using the approach I adopted?

[Andre601]

We're always open for PRs that correct outdated or incorrect documentation.
Just make sure you're following the general styling of the docs.