Generating doc site locally

You can use the composer command composer doxygen-docker. This will generate the static HTML for the docs site in the docs/php directory of this repo.

This command uses the docker-registry.wikimedia.org/releng/doxygen:latest docker image (releng/doxygen source).

Structure

The structure of the site is dictated by the @subpage relations.

The top level of the tree of pages is docs/index.md.

Markdown

Markdown documentation: http://doxygen.nl/manual/markdown.html

Linking to other markdown files

The easiest way to link to another markdown file is to use a reference link and add the full reference to the Automatic Header Id at the bottom of the file.
It's recommended to order the reference links at the bottom of the page in alphabetical order for easier parsing.
NOTE: Reference links are case-insensitive (see troubleshooting below).

Basic link to the [Data Access] page. The text between the square brackets is used as the link text.\n
Link to the [Wikibase Client][wb-client] page with custom link text (markdown version).\n
Link to the [wb-repo] page with custom link text (`@ref` version).\n
 
[Data Access]: @ref docs_components_data-access
[wb-client]: @ref docs_components_client
[wb-repo]: @ref docs_components_repo "Wikibase Repo"

The example above will render as between the horizontal lines below:

Basic link to the Data Access page. The text between the square brackets is used as the link text.
Link to the Wikibase Client page with custom link text (markdown version).
Link to the Wikibase Repo page with custom link text (@ref version).

This allows the main text to be easily read while only having to specify the target once. This also avoids manually maintaining Header Id attributes at the top of files.

Automatic Header Id

Doxygen 1.9 changed the way markdown files are referenced internally (see this GitHub bug) by replacing all special characters with an underscore (_). This caused many references to files that had a dash (-) in their filename to break.

In order to provide stable references to markdown files, without having to manually maintain Header Id attributes, an input filter script was created at build/doxygen-markdown-auto-header-id-filter.sh. Using the FILTER_PATTERNS option, this script is executed on each file with a .md extension just before Doxygen parses it, silently adding a Header Id attribute based in its filepath and filename. These Header Id attributes are only seen by Doxygen and never written to file.

For this script to automatically add a Header Id, the following rules must be met:

The file must end in .md
The file must contain a markdown header in the format <hash><space><header text>, e.g., # Example header
The header must be on the first line of the markdown file
The first line must not contain a Header Id (so that you can provide your own one if required)

The script creates the Header Id in the format <path_to_file_from_Wikibase_root><FilenameWithoutExtension>. For example, to link to the "docs/topics/change-propagation.md" file use @ref docs_topics_change-propagation. The same reference works for the @subpage command as well.

Diagrams

Doxygen allows you to incorporate multiple types of diagrams in your docs.

The ones we currently use are listed below:

dot

Command docs: https://www.doxygen.nl/manual/commands.html#cmddot
Spec docs: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
Visual tool: http://viz-js.com/
Example: Item & Property Terms

msc

Command docs: https://www.doxygen.nl/manual/commands.html#cmdmsc
Spec docs: http://www.mcternan.me.uk/mscgen/
Visual tool: https://mscgen.js.org/
Example: Change propagation

Troubleshooting

Reference links are case-insensitive

[IdGenerator] will link to the Wikibase docs about the `IdGenerator` interface.\n
[idGenerator] will **NOT** link to the Wikibase option `idGenerator`, but instead to the `IdGenerator` interface.\n
[repo_idGenerator] will link to the Wikibase option `idGenerator`.
 
[IdGenerator]: @ref Wikibase::Repo::Store::IdGenerator
[idGenerator]: @ref repo_idGenerator "This is ignored"
[repo_idGenerator]: @ref repo_idGenerator "idGenerator"

The example above will render as between the horizontal lines below:

IdGenerator will link to the Wikibase docs about the IdGenerator interface.
idGenerator will NOT link to the Wikibase option idGenerator, but instead to the IdGenerator interface.
idGenerator will link to the Wikibase option idGenerator.