Re: [ptxdist] [ptxdist-commit] [public/git/ptxdist] 15/26: Doc: improve the 'build the docs' documentation

[Juergen Borleis]

On Thursday 23 November 2017 14:51:16 Roland Hieber wrote:
> [...]
>
> > +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?

The Python experts should answer this load and clear... ;)

Cheers,
Jürgen

-- 
Pengutronix e.K.                             | Juergen Borleis             |
Industrial Linux Solutions                   | http://www.pengutronix.de/  |

___
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [ptxdist-commit] [public/git/ptxdist] 15/26: Doc: improve the 'build the docs' documentation

[Roland Hieber]

Hi,

On 23.11.2017 14:29, gitolite+pub...@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 
AuthorDate: Tue Nov 14 16:33:43 2017 +0100

 Doc: improve the 'build the docs' documentation
 
 Signed-off-by: Juergen Borleis 

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

___
ptxdist mailing list
ptxdist@pengutronix.de