Initial support for pages

antidox/templates/compound.xsl

@@ -116,7 +116,7 @@
     <!--Small workaround for groups without @brief -->
     <xsl:template match="/compounddef"/>
 
-    <xsl:template match="/compounddef[briefdescription//text() and (@kind = 'group' or @kind = 'file')]">
+    <xsl:template match="/compounddef[briefdescription//text() and (@kind = 'group' or @kind = 'file' or @kind = 'page')]">
         <section>
         <xsl:attribute name="ids">c.<xsl:value-of select="@id"/></xsl:attribute>
         <xsl:attribute name="names"><xsl:value-of select="@id"/>|<xsl:value-of select="compoundname"/>[<xsl:value-of select="@kind"/>]</xsl:attribute>
@@ -127,7 +127,7 @@
         <!-- See below for an explanation of why we dissolve paragraphs with headings -->
         <xsl:apply-templates select="detaileddescription/para[descendant::heading]/child::*[not(preceding::heading or self::heading)]|
                                      detaileddescription/para[not(preceding::heading or descendant::heading)]"/>
-        <xsl:apply-templates select="detaileddescription/para/heading[@level=1]"/>
+        <xsl:apply-templates select="detaileddescription/para/heading[@level=1]|detaileddescription/sect1|detaileddescription/sect2"/>
         </xsl:if>
         </section>
     </xsl:template>
@@ -160,6 +160,14 @@
         </desc>
     </xsl:template>
 
+    <xsl:template match="detaileddescription/sect1|detaileddescription/sect2">
+        <section>
+        <xsl:attribute name="ids"><xsl:value-of select="@id"/></xsl:attribute>
+        <title><xsl:apply-templates select="title/text()"/></title>
+        <xsl:apply-templates/>
+        </section>
+    </xsl:template>
+
     <!-- doxygen does not encapsulate a header and its content in a container,
     instead it just intercalates both. See the following post to understand
     what we are doing here:
@@ -176,7 +184,7 @@
     The important thing is that in (1) and (1.1) the test is done against heading of all
     levels, while the comparison in (2) is only with headings at the current level.
     -->
-    <xsl:template match="detaileddescription/para/heading">
+    <xsl:template match="detaileddescription/para/heading|sect1/para/heading">
         <xsl:variable name="heading" select="generate-id(.)"/>
         <xsl:variable name="level" select="number(@level)"/>
         <!-- TODO: add section ID (how do we handle duplicates?) -->

doc/source/guide.rst

@@ -220,7 +220,7 @@ Events
   and underscore:
 
   .. literalinclude:: ../../examples/riot/conf.py
-   :lines: 166-181,193-195
+   :lines: 169-184,218-220
 
 
 .. event:: antidox-db-loaded (app, db)

doc/source/overview.rst

@@ -20,11 +20,6 @@ Objectives
 * Reuse API docs made with Doxygen in a Sphinx project.
 * Provide a smooth transition between 100% automatic API docs (what Doxygen
   generates) and semi-manual documentation.
-
-  .. todo::
-
-    Add Autoindex-like functionality.
-
 * Have sensible defaults for automatic documentation generation while allowing
   customization.
 * Deal with big projects efficiently: the main tool in use now (Breathe)

doc/source/templating.rst

@@ -109,11 +109,6 @@ XPath extension functions
   Generate a :ref:`target string <entity_references>` from a refid. This
   function maps to  :py:meth:`antidox.doxy.DoxyDB.refid_to_target`.
 
-  .. todo::
-
-    antidox-indexnode_ should recognize targets in "name" attributes and set
-    the "initial" letter correctly for the index.
-
 
 .. xpath-func:: antidox:lower-case(node_or_text)
 

examples/riot/Makefile

@@ -14,13 +14,18 @@ STUBGEN       ?= python $(STUBSCRIPT)
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help html xml sphinx-clean doxy-clean gen-clean clean view
+.PHONY: help html xml sphinx-clean doxy-clean gen-clean clean view sphinx-prereq
 
-INDICES ?= generated/file-index.rst generated/group-index.rst
+INDICES ?= generated/file-index.rst generated/group-index.rst generated/page-index.rst
+
+SPHINX_PREREQ = RIOT/doc/doxygen/xml $(INDICES)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-html xml pickle: RIOT/doc/doxygen/xml $(INDICES)
+
+sphinx-prereq: $(SPHINX_PREREQ)
+
+html xml pickle: $(SPHINX_PREREQ)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 generated/%-index.rst: RIOT/doc/doxygen/xml $(STUBSCRIPT)
@@ -31,7 +36,7 @@ RIOT/doc/doxygen/xml: RIOT/doc/doxygen/Makefile
 	touch $@
 
 # The file "doxy-xml" will contain the location of the xml directory
-: RIOT/doc/doxygen/xml
+doxy-xml: RIOT/doc/doxygen/xml
 	$(file >$@,$^)
 
 sphinx-clean:

examples/riot/conf.py

@@ -14,8 +14,11 @@
 #
 import os
 import sys
+import pathlib
+
 sys.path.insert(0, os.path.abspath('../..'))
 
+this_dir = pathlib.Path(__file__).parent
 
 # -- Project information -----------------------------------------------------
 
@@ -190,6 +193,29 @@ def group_no_files(app, this, options, children):
             children.remove(el)
 
 
+# -- Hacks for Read the Docs ------------------------------------------
+#  This will only be used when we are inside RTD
+#  Taken from http://breathe.readthedocs.io/en/latest/readthedocs.html
+
+import subprocess
+
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+def _run_cmd(cmd):
+    """Run an arbitrary command and check exit status"""
+    try:
+        retcode = subprocess.call(cmd, shell=True)
+        if retcode < 0:
+            sys.stderr.write("command terminated by signal %s" % (-retcode))
+    except OSError as e:
+        sys.stderr.write("command execution failed: %s" % e)
+
+def generate_doxygen(app, config):
+    """Run the doxygen make commands if we're on the ReadTheDocs server"""
+    if read_the_docs_build:
+        _run_cmd("make -C {} sphinx-prereq".format(pathlib.Path(this_dir, "..")))
+
 def setup(app):
     app.connect("antidox-include-children", struct_no_undescore)
     app.connect("antidox-include-children", group_no_files)
+    app.connect("config-inited", generate_doxygen)

examples/riot/gen_stubs.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """Generate stubs for Doxygen Compounds.
 
 This is not part of the antidox module because there is no one-size-fits-all
@@ -23,7 +24,7 @@
 
 """
 
-OPTIONS = {doxy.Kind.FILE: ":noindex:", doxy.Kind.GROUP: ""}
+OPTIONS = {doxy.Kind.FILE: ":noindex:"}
 
 INDEX_HEAD = """
 Index of {}s
@@ -53,14 +54,13 @@ def prepare_dir(out_dir, kind):
 
 def gen_stubs(doxy_db, kind_dir, kind):
     entities = doxy_db.find((kind,))
+    options = OPTIONS.get(kind, "")
 
     for result in entities:
         members, compounds = doxy_db.find_children(result.refid)
-        if not (members or compounds):
-            continue
 
         outfile = _rst_at(kind_dir, result.refid)
-        outfile.write_text(COMPOUND_TEMPLATE.format(result, OPTIONS[kind]))
+        outfile.write_text(COMPOUND_TEMPLATE.format(result, options))
 
         yield result
 
@@ -79,13 +79,11 @@ def main():
     parser = argparse.ArgumentParser(
                     description="Example antidox stub generator")
 
-    parser.add_argument('--groups', help="Generate stubs for groups.",
-                        dest='kinds', action='append_const',
-                        const=doxy.Kind.GROUP)
-
-    parser.add_argument('--files', help="Generate stubs for files.",
-                        dest='kinds', action='append_const',
-                        const=doxy.Kind.FILE)
+    for s in ('group', 'file', 'page'):
+        parser.add_argument('--{}s'.format(s),
+                            help="Generate stubs for {}s.".format(s),
+                            dest='kinds', action='append_const',
+                            const=doxy.Kind.from_attr(s))
 
     parser.add_argument('xml_dir', help="Doxygen xml dir.",
                         type=pathlib.Path)

examples/riot/index.rst

@@ -6,14 +6,9 @@ This is the unofficial documentation for `riot`_.
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
+   :glob:
 
-   group_example
-   core_msg
-   compound_example2
-   struct_example
-   union_example
-   file_example2
-   file_example
+   generated/page/*
 
 .. toctree::
    :maxdepth: 1