Commit db562ce1 authored by Antoine Beaupré's avatar Antoine Beaupré

fix cross-referencing across projects

parent a8088cdc
......@@ -62,14 +62,20 @@ class PackageExtractor(object):
:param str root: directory where to find packages
:param str destdir: where to store the extract pages
:param bool dryrun: if True, do not actually write packages'''
# this takes one second to load, swallow the cost now instead of
# for every package
#: this takes one second to load, swallow the cost now instead of
#: for every package
self.apt_cache = apt.Cache()
#: the files written during extraction
self.files = []
#: the root of the mirror to look files in
self.root = root
#: the directory where to write extracted files
self.destdir = destdir
#: do not write anything if True
self.dryrun = dryrun
#: cache of compiled :attr:`regex` patterns
self._regexes = None
#: regex patterns of files to extract
self.patterns = regex
@property
......@@ -87,7 +93,7 @@ class PackageExtractor(object):
'''callback to actually write files in archive
this will check for the internal regex list and write the
given file in :attr:`PackageExtractor.destdir`, creating missing
given file in :attr:`destdir`, creating missing
directories as needed.
only the part that is matching the pattern is extracted,
......@@ -279,10 +285,11 @@ class PackageMirror(object):
@property
def packages(self):
"""return the mirror packages as a set of <package, version> pairs
"""return the mirror packages as a set of ``<package, version>`` pairs
.. note:: This is just like calling :func:`ls`, except there is
a cache to avoid calling it multiple times.
.. note: This is just like calling :func:`ls`, except there is
a cache to avoid calling it multiple times.
"""
if self._packages is None:
self._packages = list(self.ls())
......
......@@ -130,10 +130,13 @@ class JinjaRenderer(object):
:param bool dryrun: do not write anything in any case, useful
to test cache detection
'''
#: template to use to render the data
self.template = template
#: if we should check timestamps before writing
self.cache = cache
#: if True, do not write
self.dryrun = dryrun
# source file currently processed
#: source file currently processed
self.source = None
def generated_time(self):
......@@ -143,11 +146,12 @@ class JinjaRenderer(object):
def render(self, target, **data):
'''render template with given data
if ``pageinfo`` isn't provided in :attr:`data`, it is set to
if ``pageinfo`` isn't provided in :data:`data`, it is set to
the output of :func:`generated_time`.
:param str target: path to the target file
:param dict data: set of parameters passed to Template.render()
:param dict data: set of parameters passed to :meth:`~jinja2.Template.render`
'''
if 'pageinfo' not in data:
data['pageinfo'] = self.generated_time()
......@@ -246,7 +250,7 @@ class CommandRenderer(JinjaRenderer):
:param str target: path to the output file
:param dict data: remaining arguments passed as is to
:func:`JinjaRenderer.render`
:raises CommandRendererError: if command fails to convert given page
:raises :class:`CommandRendererError`: if command fails to convert given page
'''
# w3m parser requires absolute paths
......@@ -386,7 +390,7 @@ def find_files(directory, patterns):
command to run
.. todo:: this may be slow in large directories and may be
reimplemented with :func:`scandir` if we ever depend on
reimplemented with :func:`os.scandir` if we ever depend on
Python 3.5 or later.
:return: ``module``, ``path`` tuples
......
......@@ -19,7 +19,7 @@ opening the same package file multiple times.
.. automodule:: debmans.extractor
:members:
.. note:: the documentation for :mod:`click` functions is
.. note:: the documentation for :mod:`~click` functions is
incomplete. they should actually be turned into usage page
and manpages, see `this issue
<https://github.com/pallets/click/issues/381>`_ for details.
......@@ -64,9 +64,9 @@ All this code is here rather than in ``__init__.py`` to avoid
requiring too many dependencies in the base module, which contains
useful metadata for ``setup.py``.
This uses the :mod:`click` module to define the base command and
This uses the :mod:`~click` module to define the base command and
options, which then get passed to subcommands through the ``obj``
parameter, see :attr:`pass_obj` in the click documentation.
parameter, see :func:`~click.pass_obj` in the click documentation.
.. automodule:: debmans.__main__
:members:
......
......@@ -12,6 +12,7 @@ sys.path.insert(0, os.path.abspath('..'))
extensions = [
'sphinx.ext.todo', # .. todo:: items
'sphinx.ext.autodoc', # parse API docs
'sphinx.ext.intersphinx',
'sphinx.ext.coverage', # check for documentation coverage
'sphinx.ext.viewcode', # show code samples
]
......@@ -70,6 +71,13 @@ html_context = {
'source_url_prefix': "https://gitlab.com/anarcat/debmans/blob/HEAD/doc/",
'source_suffix': '.rst',
}
intersphinx_mapping = {
'click': ('http://click.pocoo.org/', None),
'jinja': ('http://jinja.pocoo.org/docs/', None),
'python': ('https://docs.python.org/3/', None),
}
# other output formats than HTML
latex_documents = [
(master_doc, 'debmans.tex', u'debmans Documentation',
......
......@@ -97,7 +97,7 @@ description in ``<meta description="...">`` and use the `magic markers
(``<!--htdig_noindex-->ignored<!--/htdig_noindex-->``) to make the
indexer ignore redundant bits.
See the Search section for more information about the various search
See the :ref`search-engines` for more information about the various search
software evaluated and the web interface.
Search
......@@ -256,7 +256,7 @@ Other alternatives that were considered were:
* `Bottle <http://bottlepy.org/>`_: interesting, looks simpler than Flask, if less popular?
* Django, Plone, etc: too much overhead
.. _search:
.. _search-engines:
Search engines
~~~~~~~~~~~~~~
......
Markdown is supported
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