* Re: [ptxdist] [ptxdist-commit] [public/git/ptxdist] 15/26: Doc: improve the 'build the docs' documentation
[not found] ` <E1eHrYh-00070q-SE@git.platon.pengutronix.de>
@ 2017-11-23 13:51 ` Roland Hieber
2017-11-23 14:00 ` Juergen Borleis
0 siblings, 1 reply; 2+ messages in thread
From: Roland Hieber @ 2017-11-23 13:51 UTC (permalink / raw)
To: ptxdist, Juergen Borleis
Hi,
On 23.11.2017 14:29, gitolite+public@pengutronix.de wrote:
> This is an automated email from the git hooks/post-receive script.
>
> pengutronix.michael.olbrich pushed a commit to branch master
> in repository git/ptxdist.
>
> commit efebcad7d3bd4d3d1e4cbdc280ce5bf29f298cdf
> Author: Juergen Borleis <jbe@pengutronix.de>
> AuthorDate: Tue Nov 14 16:33:43 2017 +0100
>
> Doc: improve the 'build the docs' documentation
>
> Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
> ---
> doc/including_bsp_doc.inc | 101 +++++++++++++++++++++++++++++-----------------
> 1 file changed, 64 insertions(+), 37 deletions(-)
>
> diff --git a/doc/including_bsp_doc.inc b/doc/including_bsp_doc.inc
> index c24e40e27a24..f1f65ff48acc 100644
> --- a/doc/including_bsp_doc.inc
> +++ b/doc/including_bsp_doc.inc
> @@ -1,42 +1,17 @@
> -Integrate project specific Documentaion into the Manual
> --------------------------------------------------------
> +The PTXdist User Manual
> +-----------------------
>
[...]
>
> +Using a Python virtual environment
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +*Sphinx* is *Python* based and thus can be installed via a virtual environment
> +when not globally present in the host system.
> +
> +.. code-block:: text
> +
> + $ pip3 install --upgrade --user pip virtualenv
Is there a "$ virtualenv env/" missing here? Or how is the virtualenv
expected to come into existence?
- Roland
> + $ source env/bin/activate
> + $ pip3 install sphinx
> + $ pip3 install sphinx_rtd_theme
> +
> +.. note:: Whenever you want to create the PTXdist user manual, you must first
> + source the ``env/bin/activate`` file if not already done.
> +
> Building the Documentation
> ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> @@ -56,7 +47,7 @@ documentation from the sources.
>
> The command:
>
> -::
> +.. code-block:: text
>
> $ ptxdist docs-html
>
> @@ -65,13 +56,49 @@ file for this kind of documentation is ``Documentation/html/index.html``.
>
> The command:
>
> -::
> +.. code-block:: text
>
> $ ptxdist docs-latex
>
> will build the Latex based documentation which results into the final
> *Portable Document Format* document. This result can be found in
> -``Documentation/latex/``.
> +``Documentation/latex/OSELAS.BSP-Pengutronix-Example-Quickstart.pdf``.
>
> Both commands can be executed in the BSP or the toplevel PTXdist directory
> to create the BSP specific or generic documentation respectively.
> +
> +Integrate project specific Documentation into the Manual
> +--------------------------------------------------------
> +
> +PTXdist supports the ability to integrate project specific documentation
> +into the final PTXdist manual. To do so, PTXdist handles file replacements and
> +additions, while generating the documentation.
> +
> +File replacement is working in the same manner like for all other files in
> +a PTXdist based project: a local file with the same name superseds a global file
> +from PTXdist.
> +
> +With this mechanism we can replace existing PTXdist documentation or add new one.
> +
> +If we want to add a new global section to the manual we can copy the global
> +PTXdist ``doc/index.rst`` file into our local ``doc/`` directory and adapt it
> +accordingly.
> +
> +To change or add things less intrusive we can do it on the various ``*.inc``
> +files in the PTXdist's ``doc/`` directory which define the content of the
> +sections.
> +
> +For example to change the image createn section's content, we can copy the
> +global PTXdist ``doc/user_images.inc`` into our local ``doc/`` directory and
> +adapt it to the behaviour of our project.
> +
> +In the generic documentation source many text uses variables instead of fixed
> +content. These variables are filled with values extracted from the current PTXdist
> +project prior building the final documentation. Since PTXdist projects are bound
> +to a defined PTXdist version and toolchain version, this kind of information is
> +extracted from the current settings and substituted in the documentation. This
> +behaviour ensures the documentaiton includes the project's exact definition to
> +external dependencies.
> +
> +Refer the PTXdist file ``doc/conf.py`` for more information on variable
> +substitution. This PTXdist global file can be superseded by a local copy as well.
>
--
Pengutronix e.K. | Roland Hieber |
Industrial Linux Solutions | http://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim | Phone: +49-5121-206917-5086 |
Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-5555 |
_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de
^ permalink raw reply [flat|nested] 2+ messages in thread