Inheritance documentation ========================= What is it? ----------- Inheritance adds the possibility of extending an existing sphinx project without the need of adding any kind of directives or hooks to the original document. It's been designed for projects that make an extensive use of pluggable modules such as Tryton and will work correctly with TryDoc, another sphinx extension that helps in writing documentation for Tryton modules. Installation ------------ This extension requires the following packages: - Sphinx 1.3 Use ``pip`` to install this extension straight from the Python Package Index:: pip install sphinx-inheritance Configuration ------------- In order to use inheritance you should add it to the list of extensions in conf.py:: extensions = ['sphinxcontrib.inheritance'] You should also add the list of modules that should be processed:: inheritance_modules = 'submodule1, submodule2' or:: inheritance_modules = ['submodule1', 'submodule2'] Other important configuration options for inheritance are:: inheritance_debug = False verbose = False These aren't required and these are the default values. The use of these options are detailed in the next section. Usage ----- Given an existing sphinx project, you can add text from a new module in the following way: * Create a subdirectory in the project. For example *submodule1*. * Add this directory to inheritance_modules if it must be built. * Create any number of .rst files in the directory with the following syntax:: #:after:module/file:paragraph:identifier_of_existing_paragraph# This is the text to be included after the existing paragraph. As well as any other text until the next #::# directive or the end of file. And that's it. The text provided will be added after the mentioned node. The first line is the **inherit reference**, which indicates the part of previously existing document that will be modified by this inheritance and how will be done. The inherit reference consist in four parameters separated by ':'. First one is the **position** which indicates how the current text will be included in the base document. Possible positions accepted by the extension are: * *after* which adds the supplied content after the referenced node * *before* which adds the supplied content before the referenced node * *replace* (not implemented yet) which replaces the referenced node with the supplied content. * *inside* which append the supplied content to the referenced node's content The second parameter references the **inherited source file** where is the referenced node and the file should have the '.rst' extension removed. The third is the **node type**. This is the list of suported node types: * section * title * paragraph * block_quote * literal_block * note * tip * warning * important * bullet_list * figure (only with explicit references) * toctree (only with explicit references) * comment The last parameter is the **identifier of existing node**. It could be a part or little summary about referenced node, or a less content-dependant identifier. The inherit references must to be defined explicitly with the **inheritref** directive. Defining an inherit references ****************************** This is an example of use of **inheritref** directive:: .. inheritref:: trytond_doc/maestro:title:maestros The anatomy of inherit references explained above is required even if you define them explicitly. In this case, the *inherited source file* parameter is not used, but it's recommended to reference the real source file to make easy to locate the referenced node for humans. However, for the *identifier of existing node* is recommended to choose one wiche will be robust to changes in text, to be them more inmutable and persistent throw future versions of documentation (it is the main reason to use explicit inherit references). If an inheritance is not applied or not as you expect, setting true the **inheritance_debug** option in *conf.py* file will help you. If you found a bug, provably the **verbose** option will help you to found the solution. Restrictions in position usage ****************************** There are some combinations of inherited node type and position. *after*, *before* and *replace* are allowed for all node types except *before*, which can't be used with *title* node type (it doesn't make sense insert content before the **title** node which is always the first node of a *section*). The *inside* position is allowed only for node types *section* (append any content at the end of section's content) and *bullet_list* or *toctree* (the inheritance content must to be also a **bullet_list** or *toctree* respectively and it will append its items to the inherited list). Tips **** Given that sphinx-build only re-reads files which have changed, you'll probably want to use the *-E* parameter to ensure all files are read on each build. The reason is that if one of the files changed must alter the structure of a non-modified one, the changes will take no efect. If you use the standard sphinx Makefile you can modify the *SPHINXBUILD* variable like this:: SPHINXBUILD = sphinx-build -E