Feature #295
open
Documentation: include common parts
Added by Alexey Vazhnov about 3 years ago.
Updated about 3 years ago.
Description
In user-level how-tos, some parts are common for every motherboard, for example:
- get coreboot sources
- install dependencies
Possible solutions:
Repeat these steps in every user-level how-to¶
Cons:
- Somebody have to keep them up to date
Give a links to separate pages¶
Cons:
- I don't like to jump to different pages when whole documentation can fit into one page
Include from special pages, which are not rendered by self¶
Here I will try to find a way to include common parts.
It is possible to ignore files (and to avoid errors "document isn't included in any toctree") by adding a path into exclude_patterns of conf.py.
It is possible to include reStructuredText into markdown pages by:
```eval_rst
.. include:: ../../_include/download_sources.rst
`` `
But it looks impossible to import markdown parts into markdown pages with current Sphinx configuration. mdinclude from m2r does that I need:
Note: do not use .. include:: file directive to include markdown file even if in the markdown file, please use .. mdinclude:: file instead.
But the latest m2r version from Gentoo portage doesn't work for me:
AttributeError: 'str' object has no attribute 'supported'
so it is better to try m2r2.
m2r2 not works together with recommonmark:
source_suffix '.md' is already registered
I found MyST, which can both: render Markdown + allow including Markdown (see how-tos)
```{include} ../../_include/download_sources.md
`` `
I need a feedback from coreboot team members here.
Also available in: Atom
PDF