From 104b8b4c4ce3bdf7e23362c07a8793af32195580 Mon Sep 17 00:00:00 2001 From: Max Kellermann Date: Wed, 18 Jul 2018 11:51:36 +0200 Subject: [PATCH] doc: basic support for Sphinx Migrating from DocBook to Sphinx. Editing XML is really too cumbersome. --- Makefile.am | 11 ++- configure.ac | 6 ++ doc/.gitignore | 2 + doc/conf.py | 214 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 15 ++++ 5 files changed, 246 insertions(+), 2 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/conf.py create mode 100644 doc/index.rst diff --git a/Makefile.am b/Makefile.am index f12f2a24f..73c7d194b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2528,6 +2528,9 @@ DOCBOOK_HTML = $(patsubst %.xml,%/index.html,$(DOCBOOK_FILES)) DOCBOOK_INCLUDES = $(wildcard $(srcdir)/doc/include/*.xml) +doc/html/index.html: $(srcdir)/doc/conf.py $(srcdir)/doc/*.rst + $(SPHINX) -q -b html -d doc/doctrees $(srcdir)/doc doc/html + $(DOCBOOK_HTML): %/index.html: %.xml $(DOCBOOK_INCLUDES) $(XMLTO) -o $(@D) --stringparam chunker.output.encoding=utf-8 html --stringparam use.id.as.filename=1 $< @@ -2535,13 +2538,17 @@ doc/api/html/index.html: doc/doxygen.conf @$(MKDIR_P) $(@D) $(DOXYGEN) $< -all-local: $(DOCBOOK_HTML) doc/api/html/index.html +all-local: doc/html/index.html $(DOCBOOK_HTML) doc/api/html/index.html clean-local: rm -rf $(patsubst %.xml,%,$(DOCBOOK_FILES)) - rm -rf doc/api + rm -rf doc/api doc/doctrees doc/html install-data-local: doc/api/html/index.html + $(mkinstalldirs) $(DESTDIR)$(docdir)/html $(DESTDIR)$(docdir)/html/_sources $(DESTDIR)$(docdir)/html/_static + $(INSTALL_DATA) -c doc/html/*.* $(DESTDIR)$(docdir)/html + $(INSTALL_DATA) -c doc/html/_sources/*.* $(DESTDIR)$(docdir)/html/_sources + $(INSTALL_DATA) -c doc/html/_static/*.* $(DESTDIR)$(docdir)/html/_static $(mkinstalldirs) $(DESTDIR)$(docdir)/api/html $(INSTALL_DATA) -c -m 644 doc/api/html/*.* \ $(DESTDIR)$(docdir)/api/html diff --git a/configure.ac b/configure.ac index 41d8ac086..545d6e911 100644 --- a/configure.ac +++ b/configure.ac @@ -1367,6 +1367,12 @@ dnl --------------------------------------------------------------------------- dnl Documentation dnl --------------------------------------------------------------------------- if test x$enable_documentation = xyes; then + AC_PATH_PROG(SPHINX, sphinx-build) + if test x$SPHINX = x; then + AC_MSG_ERROR([sphinx-build not found]) + fi + AC_SUBST(SPHINX) + AC_PATH_PROG(XMLTO, xmlto) if test x$XMLTO = x; then AC_MSG_ERROR([xmlto not found]) diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..1ab763002 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +/html/ +/doctrees/ diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..4228c29e2 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,214 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +# -- 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 encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Music Player Daemon' +copyright = '2003-2017 The Music Player Daemon Project' +author = 'Max Kellermann' + +# 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. +version = '0.21' +# The full version, including alpha/beta/rc tags. +release = '0.21~git' + +# 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 + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# 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 reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# 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 = 'alabaster' + +# 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 = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +# html_title = '' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..645ef5c4c --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,15 @@ +Music Player Daemon +=================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + developer + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search`