Commit e4d38ea7 authored by Louis's avatar Louis
Browse files

[doc][DRAFT] More documentation draft

parent e2dffa74
Modules
=======
TODO
.. module:: pypimonitor
``pypimonitor``
---------------
TODO
This plugin can be called to generate an HTML page, whose code is printed to standard output.
TODO sphinx argparse
.. module:: pypimonitor.httpd
``pypimonitor.httpd``
---------------
---------------------
Alternatively, this module can sever the web pages, to be accessible from a web browser. If served on http://localhost, the following URLs are available:
TODO
* http://localhost (and http://localhost/index.html): If no GET arguments, are given, display an index page, with a form to ask to render some pages. It also accpets GET arguments to specify which packages to process, and which cell plugins to use.
* http://localhost/foo/bar: When running the server, a directory ``DIR`` is given as argument. When calling this URL, a file ``DIR/foo/bar.yaml`` is searched, and if it exists, this file is processed to render the HTML page.
YAML configuration files
========================
TODO
Some plugins try to guess the appropriate required values, but it is not always possible. For instance, the :class:`TODO readthedocs` cannot guess the documentation URL, since it can differ from http://TODO package.readthedocs.io (for instance, TODO sphinxcontrib-packages documentation URL is http://packages.readthedocs.io and not http://spinxcontrib-packages.readthedocs.io). Thus, it may be necessary to provide additional information. This can be done using YAML files.
Processing YAML files
---------------------
Configuration files can be processed by both :mod:`pypimonitor` command line interface, and by the :mod:`pypimonitor.httpd` web sever. See the relevant documentation for more information.
Writing YAML files
------------------
Example
"""""""
The `example page <TODO>`_ is produced using the following YAML file:
.. literalinclude:: TODOspalax.yaml
:language: yaml
:linenos:
Configuration options
"""""""""""""""""""""
The YAML configuration is a dictionary, with the following keys : `default`, `cells`, `packages`. There can be additionnal keys, used by somme cell plugins (TODO link) (at the time I am writing this, no plugin uses this).
In the following example, the YAML configuration file is reffered as a Python :class:`dict`.
``cell`` option
^^^^^^^^^^^^^^^
TODO explicit definition of cell plugin to use
``packages``
^^^^^^^^^^^^
This is a dictionary of dictionaries: the keys are the pypi package names, and the values are either nothing (if the default values are sufficient to process this package), or a dictionary of cell options: the keys of this "sub-dictionary" are the cell names, and the values are dictionary of cell options.
For instance, in the `example <YAML>` TODO lien:
* package `fullcoverage` uses only default values, so it is mentionned without options;
* however, package `sphinxcontrib-packages` has, as a value, ``{'readthedocs': {'slug': 'packages'}}``, which means that options ``{'slug': 'packages'}`` is passed to the `readthedocs` (TODO lien) plugin (which means that the documentation URL is http://packages.readthedocs.io instead of http://sphinxcontrib-packages.readthedocs.io).
``cells``
^^^^^^^^^
If `config['cells']` is not defined, the list of columns is deduced from the cells used in the package options. This option has two purposes:
* explicitely set the list of columns (for instance, in the example TODO lien, since `color` is never referenced in package options (every package use the default options for this plugin), it would not appear in the generated HTML file if it were not present in the `config['cells']` list;
* set the order of those columns.
The values of this list can be:
* a cell plugin (TODO lien) keyword, in which case, unless `otherwise specified` (TODO lien vers cell option), the plugin used to render this cell is the corresponding plugin, and the title of the column is the title of this plugin;
* or an arbitrary text, in which case each package has to explicitely define (TODO lien) its cell plugin for this cell, or the cell plugin to use has to be defined in the ``default`` value (TODO lien).
``default``
^^^^^^^^^^^
Default cell parameters can be set, and apply to every package (unless a different parameter is set specifically for this program). This option is a dictonary, where:
* keys are the column names (as referenced in the ``cells`` option);
* values are dictionary of options, which are applied to every package, unless the package explicitely specified a different option.
For instance, in the example (TODO lien), the ``default`` configuration contains::
CI:
cell: gitlabci
server: http://framagit.org
user: spalax
This means that, unless a package specifies something else:
* the plugin used to render the cells is `gitlabci` (TODO lien);
* the gitlab server is http://framagit.org (and not the plugin default http://gitlab.com);
* the user is ``spalax`` (TODO lien)
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment