Commit 99aa2372 authored by Louis Paternault's avatar Louis Paternault
Browse files

[doc] Documentation finished

parent 1edf90b5
- Project management
- [ ] Document and add screenshot
- [x] Document and add screenshot
- [ ] Publish on framagit and pypi
- [ ] Make an example documentation file
- [x] Make an example documentation file
......@@ -34,6 +34,7 @@ extensions = [
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'sphinxarg.ext',
]
# Add any paths that contain templates here, relative to this directory.
......@@ -295,4 +296,4 @@ texinfo_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}
intersphinx_mapping = {'https://docs.python.org/3': None}
......@@ -6,7 +6,14 @@
Welcome to PypiMonitor's documentation!
=======================================
TODO
An HTML dashboard to monitor your `PyPI packages <http://pypi.python.org>`_. It
displays a line charts showing the evolution of downloads across versions, and
a set of badges (download statistics, `readthedocs <http://readthedocs.io>`__ badge,
continuous integration, etc.). See :ref:`the example <example>` below.
It is available as a :mod:`command line interface <pypimonitor>` that generates
the HTML code, and as a :mod:`web server <pypimonitor.httpd>`, to generate and
serve this dashboard.
Contents:
......@@ -17,6 +24,13 @@ Contents:
yaml
plugins
.. _example:
Example
=======
The :ref:`example configuration file <yamlexample>` produces the following output (click to enlarge).
|example|
Indices and tables
......
......@@ -8,7 +8,9 @@ Modules
This plugin can be called to generate an HTML page, whose code is printed to standard output.
TODO sphinx argparse
.. argparse::
:module: pypimonitor.__main__
:func: commandline_parser
.. module:: pypimonitor.httpd
......@@ -17,5 +19,5 @@ TODO sphinx argparse
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:
* 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.
* 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 accepts 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 :ref:`is processed <yaml>` to render the HTML page.
......@@ -24,6 +24,8 @@ Produce a square of the same color of the corresponding download chart line. Tak
Produce an empty cell. Takes no arguments.
.. _error:
``error``
"""""""""
......@@ -51,10 +53,12 @@ Produce a link to an URL.
Gitlab
^^^^^^
.. _gitlabci:
``gitlabci``
""""""""""""
Produce a badge for latest `gitlabCI <//about.gitlab.com/gitlab-ci/>`_ build.
Produce a badge for latest `gitlabCI <//about.gitlab.com/gitlab-ci/>`__ build.
* ``server`` (default `http://gitlab.com`)
URL of the gitlab server.
......@@ -75,13 +79,15 @@ PyPI
Package home page, retrieved from Pypi metadata.
`Readthedocs <http://readthedocs.io>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
`Readthedocs <http://readthedocs.io>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _Readthedocs:
``readthedocs``
"""""""""""""""
`Readthedocs <http://readthedocs.io>` build badge.
`Readthedocs <http://readthedocs.io>`__ build badge.
* ``slug``
Repository name, if different from the pypi package name.
......@@ -161,7 +167,7 @@ Jinja2
Default and Required arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A built-in features eases processing default and required arguments, for simple
A built-in feature eases processing default and required arguments, for simple
cases. This is automatically done before calling the
:meth:`Cell.render` method.
......
......@@ -3,7 +3,7 @@
YAML configuration files
========================
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.
Some plugins try to guess the appropriate required values, but it is not always possible. For instance, plugin :ref:`Readthedocs` cannot guess the documentation URL, since it can differ from ``http://<PypiPackageName>.readthedocs.io`` (for instance, the documentation URL of `sphinxcontrib-packages <http://pypi.python.org/pypi/sphinxcontrib-packages>`_ 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
---------------------
......@@ -13,26 +13,35 @@ Configuration files can be processed by both :mod:`pypimonitor` command line int
Writing YAML files
------------------
.. _yamlexample:
Example
"""""""
The `example page <TODO>`_ is produced using the following YAML file:
The `example page <_static/spalax.html>`_ is produced using the following YAML file:
.. literalinclude:: TODOspalax.yaml
.. literalinclude:: ../examples/spalax.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).
The YAML configuration is a dictionary, with the following keys : `default`, `cells`, `packages`. There can be additionnal keys, used by somme :mod:`cell plugins <pypimonitor.cell>` (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`.
.. _celloption:
``cell`` option
^^^^^^^^^^^^^^^
TODO explicit definition of cell plugin to use
The cell plugin used to render column `foo` of line `mypackage` is the plugin having as keyword (by order of precedence):
- value of `config['packages']['mypackage']['foo']['cell']` (to explicitely set the plugin to use for a single package);
- value of `config['default']['foo']['cell']` (to explicitely set the default plugin to use for a whole column);
- `foo` (at last, the column reference is used as the cell plugin keyword);
- the default :ref:`error` plugin.
``packages``
......@@ -40,22 +49,26 @@ TODO explicit definition of cell plugin to use
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:
For instance, in the :ref:`example <yamlexample>`:
* 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).
* however, package `sphinxcontrib-packages` has, as a value, ``{'readthedocs': {'slug': 'packages'}}``, which means that options ``{'slug': 'packages'}`` is passed to the :ref:`Readthedocs` plugin (which means that the documentation URL is http://packages.readthedocs.io instead of http://sphinxcontrib-packages.readthedocs.io).
.. _configcells:
``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;
* explicitely set the list of columns (for instance, in :ref:`the example <yamlexample>`, 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).
* a :mod:`cell plugin <pypimonitor.cell>` keyword, in which case, unless :ref:`otherwise specified <celloption>`, 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 :ref:`explicitely define <configcells>` its cell plugin for this cell, or the cell plugin to use has to be defined in the ``default`` value (see :ref:`default`).
.. _default:
``default``
^^^^^^^^^^^
......@@ -65,7 +78,7 @@ Default cell parameters can be set, and apply to every package (unless a differe
* 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::
For instance, in :ref:`the example <yamlexample>` the ``default`` configuration contains::
CI:
cell: gitlabci
......@@ -74,6 +87,6 @@ For instance, in the example (TODO lien), the ``default`` configuration contains
This means that, unless a package specifies something else:
* the plugin used to render the cells is `gitlabci` (TODO lien);
* the plugin used to render the cells is :ref:`gitlabci`;
* the gitlab server is http://framagit.org (and not the plugin default http://gitlab.com);
* the user is ``spalax`` (TODO lien)
* the user is `spalax <http://framagit.org/spalax>`_.
......@@ -29,7 +29,7 @@ def commandline_parser():
parser = argparse.ArgumentParser(
prog="pypimonitor",
description="A year calendar producer.",
description="Produce an HTML dashboard to monitor your PyPI packages.",
)
parser.add_argument(
......
......@@ -99,7 +99,8 @@ class Cell:
def render(self, context, package, cell):
"""Return the HTML code corresponding to this cell.
:param context: Current `Jinja2 context <http://jinja.pocoo.org/docs/dev/api/#jinja2.runtime.Context>`_.
:param context: Current `Jinja2 context
<http://jinja.pocoo.org/docs/dev/api/#jinja2.runtime.Context>`_.
:param str package: Package name.
:param dict cell: Package arguments for this cell.
:rtype: str
......@@ -111,7 +112,8 @@ class Cell:
def render_error(context, cell, package, message):
"""Return the HTML code corresponding to an error.
:param context: Current `Jinja2 context <http://jinja.pocoo.org/docs/dev/api/#jinja2.runtime.Context>`_.
:param context: Current `Jinja2 context
<http://jinja.pocoo.org/docs/dev/api/#jinja2.runtime.Context>`_.
:param str cell: Cell name (plugin keyword).
:param str package: Package name.
:param str message: Human readable error message.
......@@ -129,7 +131,16 @@ class Cell:
class Jinja2(Cell):
"""Generic class for cells that are barely more than a template.
TODO Available variables
When this class is used to render a cell, it renders template
``self.keyword``. When doing so, the template has access to the following
variables:
- `package`: the name of the package being processed, as a string;
- `pypi`: the information about this package got from pypi, as a dictionary
(for instance http://pypi.python.org/pypi/pypimonitor/json);
- `cell`: the cell options (as defined in the :ref:`yaml` configuration,
maybe completed with :ref:`default values <defaultrequired>`) as a
dictionary.
"""
def render(self, context, package, cell):
......@@ -145,6 +156,7 @@ class Jinja2(Cell):
def template(self):
"""Return template path.
TODO
By default, this is ``cells/KEYWORD.html``. One can redefine this class
to provide alternative template path.
"""
return os.path.join("cells", "{}.html".format(self.keyword))
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