Feature #295

Documentation: include common parts

Added by Alexey Vazhnov 8 months ago. Updated 8 months ago.

Status:NewStart date:02/27/2021
Priority:NormalDue date:
Assignee:Alexey Vazhnov% Done:

0%

Category:Documentation
Target version:-

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.

History

#1 Updated by Alexey Vazhnov 8 months ago

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.

#2 Updated by Alexey Vazhnov 8 months ago

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
`` `

#3 Updated by Alexey Vazhnov 8 months ago

I need a feedback from coreboot team members here.

Also available in: Atom PDF