Contributing to this documentation

This site lives in its own repository and documents code it does not own. The sources are pinned as git submodules under src/, and the parts of the site that state facts about that code are generated from it rather than typed.

Getting a local build

git clone --recurse-submodules https://github.com/IHP-GmbH/IHP-Open-ADK-docs.git
cd IHP-Open-ADK-docs
python3 -m venv .venv
.venv/bin/pip install -r docs/requirements.txt
make -C docs preprocess
.venv/bin/sphinx-build -b html -W --keep-going docs docs/_build/html

make -C docs docs runs the whole chain including the generators and opens the result.

Important

The build must be warning free. -W is set in the Makefile and fail_on_warning: true is set for Read the Docs, so a warning is a broken build, not a cosmetic issue.

What is generated

docs/scripts/ reads the submodules and writes the rule tables, the adapter tables, the version matrices and the command line transcripts. Never edit the generated files: they are overwritten on every build.

Generator

Produces

gen_rule_tables.py

The ASM and IXN rule and parameter tables, and the rule counts.

gen_adapter_table.py

The shipped interposer and interconnect adapter tables.

gen_version_matrix.py

The pinned component matrix and the format and schema version matrix.

gen_cli_usage.py

The --help transcript of each ADK command line tool.

The generators fail the build when the source drifts from what is documented. Adding a rule to a deck without describing it, renaming a command line tool, or removing a required key from an adapter all stop the build with a diagnostic rather than silently producing a table that no longer matches the code.

Continuous integration re-runs every generator and fails if the working tree is then dirty, which is what proves the published tables match the pinned revisions.

Updating to newer sources

git submodule update --remote src/IHP-Open-ADK
make -C docs preprocess
git diff

Review the diff in the generated tables. It tells you exactly what changed in the code that this site makes claims about, and therefore which prose needs rereading.

Writing conventions

Pages are reStructuredText and follow the conventions of the sibling PDK documentation at https://ihp-open-pdk-docs.readthedocs.io.

  • Page titles use =, sections -, subsections ~.

  • Double backticks for paths, environment variables, commands and identifiers.

  • Reference other pages with :doc: and an absolute path.

  • .. warning:: is reserved for status and risk. Prefer .. note:: and .. tip:: elsewhere.

  • Rule and parameter tables are .. csv-table:: reading a generated file. The CSV has no header row; the headers live in the directive.

  • Include /common.inc on any page that uses a substitution.

Editorial rules

This section is the authoring contract. The constraints below are factual or legal rather than stylistic, and a pull request that breaches one will be sent back even if the prose is good.

  • Never describe electromagnetic or thermal results as measured. They are numerically verified.

  • Never write “signoff-grade” or “production-grade”. This is a preview release.

  • Hedge novelty claims as “to our knowledge, the first open …”. Never claim primacy over other open work in the field.

  • Never describe a complete assembly as fabricated. The interposer process has been fabricated several times at IHP, which is a statement about process maturity.

  • Never present 3Dblox as closed or proprietary. It has an open implementation.

  • Automated 2.5D place and route is a proof of concept. Do not present it as more than that.

  • Do not name a bumping or packaging vendor in the site’s own prose. Write “the bumping vendor” or “the vendor’s Cu-pillar table”. A vendor name that appears inside a file quoted verbatim from a source repository stays as it is, because changing it would make the documentation misdescribe the file.

  • The connectivity axis of assembly-level verification may be described as a concept and as scope. No implementation of it is part of this release, so the site must not name a repository, a file, a module or a result for it, and must not state or imply that it can be run today. Every mention pairs with an explicit statement that it is not part of this preview release.

  • No em-dashes and no emojis anywhere.

  • British spelling throughout, except in verbatim quotations of file names, command output and tool user-interface strings.

  • Do not present the shipped rule values as foundry rules. Read Registries and schemas for what provenance each one actually has.

  • Do not number figure captions. Write the caption text only, with no “Figure N.” prefix. numfig is deliberately off: Sphinx numbers per document, so a figure reused on two pages would carry two different numbers, and no prose on this site cites a figure by number. Every figure sits next to the paragraph it illustrates. If a paginated build is ever added, that is the moment to reconsider numfig deliberately.