Small improvements to example project.

jcarrano · Apr 4, 2019 · d35260d · d35260d
1 parent 10ad21a
commit d35260d
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 9 deletions.
diff --git a/examples/riot/Makefile b/examples/riot/Makefile
@@ -2,30 +2,36 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -j 8
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     ?= .
 BUILDDIR      ?= _build
 
+STUBSCRIPT    ?= gen_stubs.py
+STUBGEN       ?= python $(STUBSCRIPT)
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help html xml sphinx-clean doxy-clean clean view
+.PHONY: help html xml sphinx-clean doxy-clean gen-clean clean view
+
+INDICES ?= generated/file-index.rst generated/group-index.rst
 
 # 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 generated/file-index.rst
+html xml pickle: RIOT/doc/doxygen/xml $(INDICES)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-generated/file-index.rst: RIOT/doc/doxygen/xml
-	python gen_stubs.py --files $< $(dir $@)
+generated/%-index.rst: RIOT/doc/doxygen/xml $(STUBSCRIPT)
+	$(STUBGEN) --$(*F)s $< $(dir $@)
 
 RIOT/doc/doxygen/xml: RIOT/doc/doxygen/Makefile
 	$(MAKE) -C RIOT/doc/doxygen xml
+	touch $@
 
 # The file "doxy-xml" will contain the location of the xml directory
-doxy-xml: RIOT/doc/doxygen/xml
+: RIOT/doc/doxygen/xml
 	$(file >$@,$^)
 
 sphinx-clean:
@@ -35,7 +41,10 @@ doxy-clean:
 	rm -rf RIOT/doc/doxygen/xml
 	rm -rf doxy-xml
 
-clean: sphinx-clean doxy-clean
+gen-clean:
+	rm -rf generated
+
+clean: sphinx-clean doxy-clean gen-clean
 
 view: html
 	xdg-open _build/html/index.html
diff --git a/examples/riot/gen_stubs.py b/examples/riot/gen_stubs.py
@@ -19,9 +19,12 @@
    {0.kind.name}[{0.name}]
 .. doxy:c:: !{0.refid}
    :children:
+   {1}
 
 """
 
+OPTIONS = {doxy.Kind.FILE: ":noindex:", doxy.Kind.GROUP: ""}
+
 INDEX_HEAD = """
 Index of {}s
 ===============
@@ -57,7 +60,7 @@ def gen_stubs(doxy_db, kind_dir, kind):
             continue
 
         outfile = _rst_at(kind_dir, result.refid)
-        outfile.write_text(COMPOUND_TEMPLATE.format(result))
+        outfile.write_text(COMPOUND_TEMPLATE.format(result, OPTIONS[kind]))
 
         yield result
 

diff --git a/examples/riot/index.rst b/examples/riot/index.rst
@@ -12,8 +12,14 @@ This is the unofficial documentation for `riot`_.
    compound_example2
    struct_example
    union_example
-   file_example
    file_example2
+   file_example
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Indices:
+
+   generated/group-index
    generated/file-index
 
 Indices and tables