Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Dec 20, 2025

Sphinx was generating a separate page for each Cell via autosummary with :toctree: and :template: directives, causing significant build overhead for 578 cells across the documentation.

Changes

Modified 14 RST files across appliedlife/, basiclife/, and savings/ directories:

  • Removed page generation: Stripped :toctree: ../generated/ and :template: mxbase.rst from all autosummary directives
  • Added inline rendering: Appended "Cells Descriptions" section with autofunction directives for each cell

Example

Before:

.. autosummary::
   :toctree: ../generated/
   :template: mxbase.rst

   ~age
   ~age_at_entry

After:

.. autosummary::

   ~age
   ~age_at_entry

Cells Descriptions
------------------

.. autofunction:: age

.. autofunction:: age_at_entry

This eliminates 578 generated pages while maintaining the autosummary table for navigation. Cell documentation now renders inline with the parent model/space documentation.

Original prompt

This section details on the original issue you should resolve

<issue_title>Inline Rendering of lifelib Cell Documentation in Sphinx</issue_title>
<issue_description>### Background

The directories listed below are located under makedocs/source/libraries and contain .rst files used by the Sphinx documentation generator.

  • appliedlife
  • basiclife
  • savings

Each directory documents a lifelib library, which contains one or more lifelib models.

Each model is documented in a .rst file.
A model may contain a single space or multiple spaces.
If a model contains multiple spaces, each space is documented either:

  • in a separate .rst file, or
  • within the model’s main documentation file.

Models, Spaces, and Cells

Models and spaces are represented by Python modules.
They contain Cells, which are represented by Python functions.

Currently, Sphinx (via the autosummary extension) auto-generates a separate page for each Cell, based on the Cell’s docstring. This significantly increases documentation build time.


Goal

Instead of generating separate pages for each Cell, render the Cell docstrings on the same page as the corresponding model or space documentation.


Required Changes

To achieve this, apply the following steps:

1. Modify the autosummary directive

In the directories listed above, identify autosummary directives that generate separate pages for Cells and remove the :toctree: and :template: options.

2. Add a “Cells Descriptions” section

At the bottom of the same .rst file:

  • Add a section titled “Cells Descriptions”
  • For each Cell listed in the autosummary, add an autofunction directive so the Cell documentation is rendered inline.

Example

Before

.. autosummary::
   :toctree: ../generated/
   :template: mxbase.rst

   ~age
   ~age_at_entry

After

.. autosummary::

   ~age
   ~age_at_entry

Then, add the following section at the end of the file:

Cells Descriptions
------------------

.. autofunction:: age

.. autofunction:: age_at_entry

</issue_description>

Comments on the Issue (you are @copilot in this section)


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 2 commits December 20, 2025 03:03
Co-authored-by: fumitoh <8450892+fumitoh@users.noreply.github.com>
Co-authored-by: fumitoh <8450892+fumitoh@users.noreply.github.com>
Copilot AI changed the title [WIP] Add inline rendering for lifelib cell documentation in Sphinx Render Cell documentation inline instead of generating separate pages Dec 20, 2025
Copilot AI requested a review from fumitoh December 20, 2025 03:13
@fumitoh fumitoh marked this pull request as ready for review December 20, 2025 10:19
@fumitoh fumitoh merged commit d053548 into main Dec 20, 2025
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Inline Rendering of lifelib Cell Documentation in Sphinx

2 participants