GenPackageDoc 0.41.1

Documentation builder for Python packages

GenPackageDoc Description

The Python package GenPackageDoc generates the documentation of Python modules. The content of this documentation is taken out of the docstrings of functions, classes and their methods.

It is possible to extend the documentation by the content of additional files either in reStructuredText (RST) format or in LaTeX format.

The documentation is generated in four steps:

1. Files in LaTeX format are taken over immediately.
2. Files in reStructuredText format are converted to LaTeX files.
3. All docstrings of all Python modules in the package are converted to LaTeX files.
4. All LaTeX files together are converted to a single PDF document. This requires a separately installed LaTeX distribution (recommended: TeX Live). A LaTeX distribution is not part of GenPackageDoc and has to be installed separately!

How to install

GenPackageDoc can be installed in two different ways.

1. Installation via PyPi (recommended for users)

   pip install GenPackageDoc
   

   GenPackageDoc in PyPi

2. Installation via GitHub (recommended for developers)

   • Clone the python-genpackagedoc repository to your machine

     git clone https://github.com/test-fullautomation/python-genpackagedoc.git
     

     GenPackageDoc in GitHub

   • Install dependencies

     GenPackageDoc requires some additional Python libraries. Before you install the cloned repository sources you have to install the dependencies manually. The names of all related packages you can find in the file requirements.txt in the repository root folder. Use pip to install them:

     pip install -r requirements.txt
     

     Additionally install LaTeX (recommended: TeX Live). This is required.

     Additionally install PlantUML. This is an option.

   • Configure dependencies

     GenPackageDoc uses LaTeX to generate the documentation in PDF format. GenPackageDoc also supports PlantUML. PlantUML requires Java.

     GenPackageDoc needs to know where to find those applications. This is defined in the GenPackageDoc configuration file

     packagedoc\packagedoc_config.json
     

     Before you start the installation you have to introduce the following environment variables, that are used in packagedoc_config.json:

     • GENDOC_LATEXPATH : path to pdflatex executable
     • GENDOC_PLANTUML_PATH : path to plantuml executable (optional)
     • JAVA_HOME : path to java executable (optional, only in case of PlantUML is used)

   • Use the following command to install GenPackageDoc:

     setup.py install
     

How to use

GenPackageDoc provides a toolchain to generate documentation out of Python sources that are stored within a repository. GenPackageDoc is also designed to be able to consider setup informations of a repository.

The impact is: There is a deep relationship between the repository containing the sources to be documented, and the sources and the configuration of GenPackageDoc itself. Therefore GenPackageDoc needs to be configured to get to know about things like the path to the package sources and the desired name of the generated documentation PDF file.

GenPackageDoc is able to use it's own sources to document itself. Therefore the complete GenPackageDoc repository can be used as example about about writing a package documentation.

At the end of all preparations you will get for your own repository a PDF document that will look like this: GenPackageDoc.pdf (that is the detailed documentation of GenPackageDoc).

Feedback

To give us a feedback, you can send an email to Thomas Pollerspöck

In case you want to report a bug or request any interesting feature, please don't hesitate to raise a ticket.

Maintainers

Holger Queckenstedt

Thomas Pollerspöck

Contributors

Holger Queckenstedt

Thomas Pollerspöck

License

Copyright 2020-2023 Robert Bosch GmbH

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.