From 8630be655dd89d20a6de10fd8eb25475d17f2b30 Mon Sep 17 00:00:00 2001 From: Juergen Borleis Date: Tue, 21 Jun 2016 15:24:46 +0200 Subject: Doc: add a section how to generate the documentation This also includes some hints how to extend and/or adapt the existing documentation. It defines the external dependencies to be able to build the documentation as well. Signed-off-by: Juergen Borleis --- doc/daily_work_section.rst | 1 + doc/including_bsp_doc.inc | 73 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 doc/including_bsp_doc.inc diff --git a/doc/daily_work_section.rst b/doc/daily_work_section.rst index c5c963e4e..daec36dca 100644 --- a/doc/daily_work_section.rst +++ b/doc/daily_work_section.rst @@ -4,4 +4,5 @@ Various Aspects of Daily Work .. include:: daily_work.inc .. include:: nfsroot.inc .. include:: working_with_git_sources.inc +.. include:: including_bsp_doc.inc .. include:: faq.inc diff --git a/doc/including_bsp_doc.inc b/doc/including_bsp_doc.inc new file mode 100644 index 000000000..59b69c01d --- /dev/null +++ b/doc/including_bsp_doc.inc @@ -0,0 +1,73 @@ +Integrate project specific Documentaion 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. + +Requirements to build the Documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Fonts: + - *Liberation Sans/Liberation Sans Bold* or *DejaVu Sans/DejaVu Sans Bold* + (for the "Portable Document Format", e.g. PDF) + - *Inconsolata*, *DejaVu Sans Mono* or *Liberation Sans Mono* + (for the "Portable Document Format", e.g. PDF) + +Tools: + - *Sphinx* version 1.3.4, better 1.4.2 (for all kind of document formats) + - *TeX Live 2016* (for the "Portable Document Format", e.g. PDF) + +Building the Documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PTXdist comes with support to generate *HTML* or *Portable Document Format* based +documentation from the sources. + +The command: + +:: + + $ ptxdist docs-html + +will build the HTML based documentation into ``Documentation/html`` and the entry +file for this kind of documentation is ``Documentation/html/index.html``. + +The command: + +:: + + $ 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/``. -- cgit v1.2.3