https://github.com/readthedocs/sphinxcontrib-multisrc

Sphinx multiple source path support
https://github.com/readthedocs/sphinxcontrib-multisrc

Last synced: 4 days ago
JSON representation

Sphinx multiple source path support

• Host: GitHub
• URL: https://github.com/readthedocs/sphinxcontrib-multisrc
• Owner: readthedocs
• Created: 2018-12-12T05:26:34.000Z (almost 6 years ago)
• Default Branch: main
• Last Pushed: 2022-03-17T20:33:47.000Z (over 2 years ago)
• Last Synced: 2024-05-09T15:49:27.862Z (6 months ago)
• Language: Python
• Size: 7.81 KB
• Stars: 2
• Watchers: 4
• Forks: 6
• Open Issues: 1
• Metadata Files:
  • Readme: readme.rst

Awesome Lists containing this project

README

        
sphinxcontrib-multisrc

======================

This extension gives Sphinx a fallback path so that a common source pattern can

be used to author documentation. In addition to falling back to the common

source, Jinja can also be used as a transform to extend source files from the

common source.

Configuration

-------------

Multiple source paths can be configured using an option in your configuration::

    extensions = [

        ...

        'sphinxcontrib.multisrc',

    ]

    multisrc_paths = [

        '../submodule/docs',

        '.',

    ]

Extending docs

--------------

Extending a source file can be accomplished with Jinja. All you need is a source

file that can be extended, using Jinja blocks. For example, assuming the

configuration file above, a ``../submodule/docs/foo.rst`` would look like::

    Base source file

    ================

    {% block main %}

    This is the base source file

    {% endblock %}

In the local environment source path, ``./foo.rst`` can extend the base source

file::

    {% extends 'foo.rst' %}

    {% block main %}

    This is extended from the base source file

    {% endblock %}