All Package Index and generated includes

The All Packages Index and its reusable package includes are generated by the All Package Index project. Handwritten guides in Software on Stanage reuse these includes and add the instructions users need to run the software.

Generated files

The current Stanage stack is el9-icelake-znver-stanage. Generated package includes are stored in referenceinfo/imports/stanage/packages/. Inspect the existing files for the package rather than assuming which includes are available.

For example, CMake provides:

Include filename	Content
cmake-sdbr-el9-icelake-znver-stanage.rst	Sidebar with version and product metadata
cmake-dscr-el9-icelake-znver-stanage.rst	Software description
cmake-ml-el9-icelake-znver-stanage.rst	Available module-load commands
cmake-inst-el9-icelake-znver-stanage.rst	Installation notes
cmake-dpnd-el9-icelake-znver-stanage.rst	Dependencies of the latest version

Include these files using reStructuredText directives, for example:

.. include:: /referenceinfo/imports/stanage/packages/cmake-ml-el9-icelake-znver-stanage.rst

Custom includes

Custom includes are maintained by hand in referenceinfo/imports/stanage/packages/custom/. Normal All Package Index synchronisation creates missing custom files without overwriting existing ones. Use these files for additional package guidance that should appear on generated software pages.

For example:

.. include:: /referenceinfo/imports/stanage/packages/custom/cmake-cust-el9-icelake-znver-stanage.rst

The generated CMake package page already includes this file after its module list. A handwritten software guide can also include it when the same guidance is relevant, avoiding duplicate instructions.

Creating a handwritten software guide

Start with the normal software page layout. Choose the appropriate application, development tool, library or parallel software section, and give the new page a unique reference label.

Reuse the package’s generated sidebar, module list and installation includes. Add concise usage instructions and relevant examples, and link the page from its category index. Do not copy the generated stack page wholesale: its stack-specific reference label and additional includes serve the All Package Index rather than a handwritten guide.

Maintaining generated information

Do not edit generated listings or includes directly. If versions, product URLs or installation metadata are incorrect, report or correct the source metadata used by the generator. This prevents the next generation run from overwriting a handwritten fix.

Keep package-specific usage explanations in the handwritten guide or a custom include shared with the generated package page. See Style Guide for conventions and Guidance dates for when to update its guidance date.