PulpQE / pulp-smash / 436 / 1
63%
master: 63%

DEFAULT BRANCH: master
Ran
Files 6
Run time 0s
Badge
Embed ▾
README BADGES
x

If you need to use a raster PNG badge, change the '.svg' to '.png' in the link

Markdown

Textile

RDoc

HTML

Rst
coverage: 74.458%. Remained the same
436.1

push

travis-ci

Ichimonji10 
Auto-generate API documentation stub files

Create script `gen_api_docs.sh`. It uses the "find" utility to search
through the `pulp_smash` and `tests` directories and, for each file
found, generates a reStructuredText document in `docs/api/`. The
generated documents are semantically identical to what is present in
`docs/api/` already.

Also:

* Update the `docs-html` make target, and make it call this new script
  before Sphinx itself.
* Make git keep the `docs/api/` directory.
* Make git ignore the reST files the script places in `docs/api/`.
* Add module `pulp_smash.__main__` to the API documentation.

How does this solution compare the current state of affairs? One
downside is that developers still must maintain the index, in
`docs/api.rst`, of all modules to be included in the API documentation.
However, there are several benefits:

* reST files no longer need to be maintained in `docs/api/*`.
* Sphinx issues a warning if the index (in `docs/api.rst`) is out of
  sync with the set of reST stubs and, therefore, the set of modules in
  the application. This has already come in to play: module
  `pulp_smash/__main__` was missing from the API documentation, and it
  has been added in response to this warning.
* It is now much easier to update the API documentation pages, as there
  is now only one template, instead of dozens.

Two alternative solutions were considered. One option is to use
`sphinx-apidoc` to generate reST files, instead of this custom script.
Unfortunately, the reST files emitted by this script are unsatisfactory,
and it is impossible to make this script use a custom template. A second
option is to use the `autosummary` Sphinx directive in `docs/api.rst`
like so:

    .. autosummary::
        :toctree: api

        pulp_smash
        pulp_smash.__main__
        pulp_smash.api
        pulp_smash.cli
        …

One can then ask the `sphinx-autogen` script to generate one reST file
for each module listed. While this works, there are more downsides:

* The `sphinx-autogen` script names imports (!) in the reST files it
  generates. This is nonsensical and generates a tremendous number of
  warnings.
* The `autosummary` Sphinx directive emits tables, instead of lists.
  While arguably useful, tabulated output is much more verbose, which
  reduces legibility and makes it harder to scan through the list of
  modules. In addition, this cannot be overridden.
* Because the `autosummary` directive drives which reST files are
  generated, it is easy for the documentation to become out of sync with
  the actual set of modules which should be documented.

Fix https://github.com/PulpQE/pulp-smash/issues/18

309 of 415 relevant lines covered (74.46%)

0.74 hits per line

Source Files on job 436.1