[elbe-devel] [PATCH] docs: generate sphinx documentation
Manuel Traut
manut at linutronix.de
Wed May 10 11:00:34 CEST 2017
This enables generating sphinx documentation.
If this change will be added to every release branch, we can generate a
website with versioned documentation using 'sphinx-versioning'.
To build the current documentation use:
$ cd doc
$ sphinx-build . _build
Signed-off-by: Manuel Traut <manut at linutronix.de>
---
.gitignore | 6 ++
docs/Makefile | 43 ++++++++++--
docs/conf.py | 157 ++++++++++++++++++++++++++++++++++++++++++++
docs/index.rst | 23 +++++++
elbepack/xsdtoasciidoc.mako | 2 +-
5 files changed, 223 insertions(+), 8 deletions(-)
create mode 100644 docs/conf.py
create mode 100644 docs/index.rst
diff --git a/.gitignore b/.gitignore
index 54592668..461dc605 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ debian/elbe-buildenv/
debian/elbe-common/
debian/elbe-control/
debian/elbe-daemon/
+debian/elbe-debianize/
debian/elbe-doc/
debian/elbe-soap/
debian/elbe-updated/
@@ -14,11 +15,16 @@ debian/elbe-bootup-check/
debian/elbe-daemon/
debian/elbe-buildchroot/
debian/elbe-adjustpkg/
+debian/debhelper-build-stamp
*.pyc
build
+docs/_build
docs/*.1
docs/*.html
docs/*.png
+docs/*.xml
+docs/elbe*.rst
+docs/article-*.rst
docs/manpage-base-url.xsl
docs/elbe-examples.txt
docs/elbe-schema-reference.txt
diff --git a/docs/Makefile b/docs/Makefile
index 771e9229..0813692c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -13,10 +13,9 @@ MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
DOC_HTML=$(MAN_HTML)
-ARTICLES = elbe-schema-reference elbe-examples
-SP_ARTICLES= elbeoverview-en quickstart
+SP_ARTICLES= elbeoverview-en quickstart elbe-schema-reference
-DOC_HTML+=$(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+DOC_HTML+=$(patsubst %,%.html,$(SP_ARTICLES))
DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
DOC_MAN5=$(patsubst %.txt,%.5,$(MAN5_TXT))
@@ -55,6 +54,9 @@ ASCIIDOC_DATA_URI = -a data-uri -a iconsdir=/usr/share/asciidoc/images/icons
all: html man
html: $(DOC_HTML)
+sphinx:
+ sphinx-build . _build
+
install: install-man install-html
install-man: man
@@ -74,7 +76,8 @@ man7: $(DOC_MAN7)
clean:
- $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
+ $(RM) -r _build
+ $(RM) article*.rst elbe*.rst *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
$(RM) *.pdf
$(RM) howto-index.txt howto/*.html doc.dep
@@ -98,13 +101,15 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
%.xml : %.txt
$(RM) $@+ $@ && \
+ $(ASCIIDOC) -d article -b docbook -agit_version=$(ELBE_VERSION) -o $@ $< && \
+ pandoc -r docbook -w rst -o $*.rst $@
+ sed -i "1s/^/************************\n\n/" $*.rst
+ sed -i "1s/^/$*\n/" $*.rst
+ sed -i "1s/^/************************\n/" $*.rst
$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
$(ASCIIDOC_EXTRA) -agit_version=$(ELBE_VERSION) -o $@+ $< && \
mv $@+ $@
-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
- $(ASCIIDOC) -a toc $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt
-
%.svg : %.dia
$(RM) $@ && \
$(DIA) --export=$@ $<
@@ -114,18 +119,42 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
$(DIA) --export=$@ $<
elbeoverview-en.html : elbeoverview-en.txt elbe-process.png emu-process.png
+ $(ASCIIDOC) -d article -b docbook -agit_version=$(ELBE_VERSION) -o elbeoverview-en.xml $< && \
+ pandoc -r docbook -w rst -o article-elbeoverview-en.rst elbeoverview-en.xml
+ sed -i "1s/^/************************\n\n/" article-elbeoverview-en.rst
+ sed -i "1s/^/ELBE Overview\n/" article-elbeoverview-en.rst
+ sed -i "1s/^/************************\n/" article-elbeoverview-en.rst
$(ASCIIDOC) -a toc2 $(ASCIIDOC_EXTRA) $(ASCIIDOC_DATA_URI) -b xhtml11 elbeoverview-en.txt
quickstart.html : quickstart.txt
+ $(ASCIIDOC) -d article -b docbook -agit_version=$(ELBE_VERSION) -o quickstart.xml $< && \
+ pandoc -r docbook -w rst -o article-quickstart.rst quickstart.xml
+ sed -i "1s/^/************************\n\n/" article-quickstart.rst
+ sed -i "1s/^/ELBE Quickstart\n/" article-quickstart.rst
+ sed -i "1s/^/************************\n/" article-quickstart.rst
$(ASCIIDOC) -a toc2 $(ASCIIDOC_EXTRA) $(ASCIIDOC_DATA_URI) -b xhtml11 quickstart.txt
elbeoverview-en-ie.html: elbeoverview-en.txt elbe-process.png emu-process.png
+ $(ASCIIDOC) -d article -b docbook -agit_version=$(ELBE_VERSION) -o $*.xml $< && \
+ pandoc -r docbook -w rst -o article-$*.rst $*.xml
+ sed -i "1s/^/************************\n\n/" $*.rst
+ sed -i "1s/^/$*\n/" $*.rst
+ sed -i "1s/^/************************\n/" $*.rst
$(ASCIIDOC) -b html5 -a icons -a toc2 -a theme=flask -o elbeoverview-en.html elbeoverview-en.txt
elbe-schema-reference.txt: ../elbepack/dbsfed.xsd ../elbepack/xsdtoasciidoc.mako
../elbe xsdtoasciidoc --output elbe-schema-reference.txt ../elbepack/dbsfed.xsd
$(ASCIIDOC) -a toc2 $(ASCIIDOC_EXTRA) $(ASCIIDOC_DATA_URI) -b xhtml11 elbe-schema-reference.txt
+elbe-schema-reference.html: %.html : %.txt
+ $(ASCIIDOC) -d article -b docbook -agit_version=$(ELBE_VERSION) -o $*.xml $< && \
+ pandoc -r docbook -w rst -o article-$*.rst $*.xml
+ sed -i "1s/^/*************************\n\n/" article-$*.rst
+ sed -i "1s/^/ELBE XML Reference\n/" article-$*.rst
+ sed -i "1s/^/*************************\n/" article-$*.rst
+ sed -i "s/<#/<#type-/g" article-$*.rst
+ $(ASCIIDOC) -a toc $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt
+
elbe-examples.txt:
./build-example-doc.sh
$(ASCIIDOC) $(ASIIDOC_EXTRA) $(ASCIIDOC_DATA_URI) -b xhtml11 elbe-examples.txt
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000..d5ea6aad
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+#
+# ELBE documentation build configuration file, created by
+# sphinx-quickstart on Mon May 8 15:56:24 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+os.system("make")
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ELBE'
+copyright = u'2017, Linutronix GmbH'
+author = u'Torben Hohn, Manuel Traut'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+from elbepack.version import elbe_version as version
+# The full version, including alpha/beta/rc tags.
+from elbepack.version import elbe_version as release
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {"rightsidebar": "true", "relbarbgcolor": "black"}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ELBEdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
+
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'ELBE.tex', u'ELBE Documentation',
+ u'Torben Hohn, Manuel Traut', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'elbe', u'ELBE Documentation',
+ [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'ELBE', u'ELBE Documentation',
+ author, 'ELBE', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+html_sidebars = { '**': ['globaltoc.html'] }
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..c347bf0c
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,23 @@
+ELBE docs
+==========
+
+.. toctree::
+ :maxdepth: 2
+ :glob:
+ :reversed:
+
+ article*
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+ :caption: man-pages
+
+ elbe*
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/elbepack/xsdtoasciidoc.mako b/elbepack/xsdtoasciidoc.mako
index c17636ae..093debdf 100644
--- a/elbepack/xsdtoasciidoc.mako
+++ b/elbepack/xsdtoasciidoc.mako
@@ -65,7 +65,7 @@ ${docindent(n.text(DOC))}
</%def>
<%def name="elementseq(n)">
- ${n.et.attrib["name"]} ('${genlink(n.et.attrib["type"])}') ${cardinality(n)}::
+ ${n.et.attrib["name"]} ${genlink(n.et.attrib["type"])} ${cardinality(n)}::
${docindent(n.text(DOC), 2)}
</%def>
--
2.11.0
More information about the elbe-devel
mailing list