Sphinx-Compendia#
Sphinx-Compendia is especially useful for documenting collections, compendiums, catalogs, inventories, compilations, digests and such. You can find a few example use cases below.
We write documentation to communicate efficiently complex topics. Sphinx-Compendia help see how the constituents of a topic are linked together and have a holistic view of what matters.
Sphinx-Compendia helps you leverage the best feature from Sphinx for the compendia that are meaningful for you and your readers.
Integrates nicely in your existing workflow. See Defining a compendium.
Powerful cross-referencing capabilities, even between separate documentation projects. Keeping links with URLs up-to-date is hard, cross-referencing with Sphinx-Compendia saves you time. See Adding content to a compendium.
Compendium-specific indices so you can browse all your documented constituent at a glance, so readers can take a step back and browse your compendia as a whole. See Indexation.
Efficient search in built web sites. See Nice search results.
Works for any reading medium Sphinx supports, from HTML pages to eReaders.
While simple by default, Sphinx-Compendia is also extensible! See Advanced customization.
Sphinx-Compendia is named after its main use-case: compendiums. The word compendia is another plural form of compendium. We use both plural forms in this documentation.
Quickstart#
Install Sphinx-Compendia
Define a topic and some constituents as an extension in your
conf.pyfile (conf)from sphinx_compendia import make_compendium def setup(app): # Provide a topic shortname and some constituents make_compendium("baking", ["recipe", "technique"], app=app)
Use the generated directives and roles, in this case
.. baking:recipe::,.. baking:technique::,:baking:recipe:and:backing:technique:.
Example use-cases#
- Writing a table-top roleplaying game adventure path as code
We will use this use case in our examples.
we are writing an adventure path in a home brewed world named Fjordlynn for some table top role-playing game. We want to document characters and locations along with some house rules for skills and magic spells.
We will create two compendia:
worldandrulefor respectively documentingcharacterandlocation, andskillandspell, generating automatically the required directives and cross-referencing roles.- Creating a user experience design system as code
Document a UX topic with personas, markets or other interesting constituents. Cross-reference these from your BDD specifications documented with Sphinx-Gherkin!
- Building IT management systems as code
Document teams, services, assets and configuration items for your ITIL (or other IT management framework) documentation.
- Cookbook as code
Publish your best meatloaf and kimchi recipes with style. You can even use Sphinx-Compendia for a printed book!
Installation#
Install Sphinx-Compendia:
pip install -U sphinx-compendia
Get started#
Tip
Get started in no time, go to our User manual section!
Links#
Sphinx-Compendia is