Changeset 669 for trunk/docs


Ignore:
Timestamp:
Dec 29, 2015, 3:02:11 PM (4 years ago)
Author:
cito
Message:

Update Sphinx conf and make files

Update the conf and make files for creating the documentation
so that newer Sphinx features are supported.

Location:
trunk/docs
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/Makefile

    r516 r669  
    33
    44# You can set these variables from the command line.
    5 SPHINXOPTS    = -aE
     5SPHINXOPTS    =
    66SPHINXBUILD   = sphinx-build
    77PAPER         =
    88BUILDDIR      = _build
     9
     10# User-friendly check for sphinx-build
     11ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
     12$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
     13endif
    914
    1015# Internal variables.
     
    1520I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
    1621
    17 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
     22.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
    1823
    1924help:
     
    2631        @echo "  htmlhelp   to make HTML files and a HTML help project"
    2732        @echo "  qthelp     to make HTML files and a qthelp project"
     33        @echo "  applehelp  to make an Apple Help Book"
    2834        @echo "  devhelp    to make HTML files and a Devhelp project"
    2935        @echo "  epub       to make an epub"
    3036        @echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
    3137        @echo "  latexpdf   to make LaTeX files and run them through pdflatex"
     38        @echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
    3239        @echo "  text       to make text files"
    3340        @echo "  man        to make manual pages"
     
    3643        @echo "  gettext    to make PO message catalogs"
    3744        @echo "  changes    to make an overview of all changed/added/deprecated items"
     45        @echo "  xml        to make Docutils-native XML files"
     46        @echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
    3847        @echo "  linkcheck  to check all external links for integrity"
    3948        @echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
     49        @echo "  coverage   to run coverage check of the documentation (if enabled)"
    4050
    4151clean:
    42         -rm -rf $(BUILDDIR)/*
     52        rm -rf $(BUILDDIR)/*
    4353
    4454html:
     
    8292        @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyGreSQL.qhc"
    8393
     94applehelp:
     95        $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
     96        @echo
     97        @echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
     98        @echo "N.B. You won't be able to view it unless you put it in" \
     99              "~/Library/Documentation/Help or install it in your application" \
     100              "bundle."
     101
    84102devhelp:
    85103        $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
     
    107125        @echo "Running LaTeX files through pdflatex..."
    108126        $(MAKE) -C $(BUILDDIR)/latex all-pdf
     127        @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
     128
     129latexpdfja:
     130        $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
     131        @echo "Running LaTeX files through platex and dvipdfmx..."
     132        $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
    109133        @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
    110134
     
    152176        @echo "Testing of doctests in the sources finished, look at the " \
    153177              "results in $(BUILDDIR)/doctest/output.txt."
     178
     179coverage:
     180        $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
     181        @echo "Testing of coverage in the sources finished, look at the " \
     182              "results in $(BUILDDIR)/coverage/python.txt."
     183
     184xml:
     185        $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
     186        @echo
     187        @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
     188
     189pseudoxml:
     190        $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
     191        @echo
     192        @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
  • trunk/docs/conf.py

    r659 r669  
    11# -*- coding: utf-8 -*-
    22#
    3 # PyGreSQL documentation build configuration file, created by
    4 # sphinx-quickstart on Thu Nov  1 07:47:06 2012.
    5 #
    6 # This file is execfile()d with the current directory set to its containing dir.
     3# PyGreSQL documentation build configuration file.
     4#
     5# This file is execfile()d with the current directory set to its
     6# containing dir.
    77#
    88# Note that not all possible configuration values are present in this
     
    1212# serve to show the default.
    1313
    14 import sys, os
     14import sys
     15import os
     16import shlex
    1517
    1618# import Cloud
     
    2224#sys.path.insert(0, os.path.abspath('.'))
    2325
    24 # -- General configuration -----------------------------------------------------
     26# -- General configuration ------------------------------------------------
    2527
    2628# If your documentation needs a minimal Sphinx version, state it here.
    2729#needs_sphinx = '1.0'
    2830
    29 # Add any Sphinx extension module names here, as strings. They can be extensions
    30 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
     31# Add any Sphinx extension module names here, as strings. They can be
     32# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
    3133extensions = ['sphinx.ext.autodoc']
    3234
     
    3436templates_path = ['_templates']
    3537
    36 # The suffix of source filenames.
     38# The suffix(es) of source filenames.
     39# You can specify multiple suffix as a list of string:
     40# source_suffix = ['.rst', '.md']
    3741source_suffix = '.txt'
    3842
     
    4448
    4549# General information about the project.
    46 project = u'PyGreSQL'
    47 copyright = u'2012, The PyGreSQL team'
     50project = 'PyGreSQL'
     51author = 'The PyGreSQL team'
     52copyright = '2015, ' + author
    4853
    4954# The version info for the project you're documenting, acts as replacement for
     
    5863# The language for content autogenerated by Sphinx. Refer to documentation
    5964# for a list of supported languages.
    60 #language = None
     65# This is also used if you do content translation via gettext catalogs.
     66# Usually you set "language" from the command line for these cases.
     67language = None
    6168
    6269# There are two options for replacing |today|: either, you set today to some
     
    7077exclude_patterns = ['_build']
    7178
    72 # The reST default role (used for this markup: `text`) to use for all documents.
     79# The reST default role (used for this markup: `text`) for all documents.
    7380#default_role = None
    7481
     
    9198
    9299
    93 # -- Options for HTML output ---------------------------------------------------
     100# If true, keep warnings as "system message" paragraphs in the built documents.
     101#keep_warnings = False
     102
     103# If true, `todo` and `todoList` produce output, else they produce nothing.
     104todo_include_todos = False
     105
     106
     107# -- Options for HTML output ----------------------------------------------
    94108
    95109# The theme to use for HTML and HTML Help pages.  See the documentation for
     
    100114# further.  For a list of options available for each theme, see the
    101115# documentation.
    102 html_theme_options = { "defaultcollapsed": True, }
     116html_theme_options = {'defaultcollapsed': True}
    103117
    104118# Add any paths that contain custom themes here, relative to this directory.
     
    126140html_static_path = ['_static']
    127141
     142# Add any extra paths that contain custom files (such as robots.txt or
     143# .htaccess) here, relative to this directory. These files are copied
     144# directly to the root of the documentation.
     145#html_extra_path = []
     146
    128147# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
    129148# using the given strftime format.
     
    167186#html_file_suffix = None
    168187
     188# Language to be used for generating the HTML full-text search index.
     189# Sphinx supports the following languages:
     190#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
     191#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
     192#html_search_language = 'en'
     193
     194# A dictionary with options for the search language support, empty by default.
     195# Now only 'ja' uses this config value
     196#html_search_options = {'type': 'default'}
     197
     198# The name of a javascript file (relative to the configuration directory) that
     199# implements a search results scorer. If empty, the default will be used.
     200#html_search_scorer = 'scorer.js'
     201
    169202# Output file base name for HTML help builder.
    170203htmlhelp_basename = 'PyGreSQLdoc'
    171204
    172205
    173 # -- Options for LaTeX output --------------------------------------------------
     206# -- Options for LaTeX output ---------------------------------------------
    174207
    175208latex_elements = {
     
    182215# Additional stuff for the LaTeX preamble.
    183216#'preamble': '',
     217
     218# Latex figure (float) alignment
     219#'figure_align': 'htbp',
    184220}
    185221
    186222# Grouping the document tree into LaTeX files. List of tuples
    187 # (source start file, target name, title, author, documentclass [howto/manual]).
     223# (source start file, target name, title,
     224#  author, documentclass [howto, manual, or own class]).
    188225latex_documents = [
    189   ('index', 'PyGreSQL.tex', u'PyGreSQL Documentation',
    190    u'The PyGreSQL team', 'manual'),
     226    (master_doc, 'PyGreSQL.tex', 'PyGreSQL Documentation',
     227     author, 'manual'),
    191228]
    192229
     
    212249
    213250
    214 # -- Options for manual page output --------------------------------------------
     251# -- Options for manual page output ---------------------------------------
    215252
    216253# One entry per manual page. List of tuples
    217254# (source start file, name, description, authors, manual section).
    218255man_pages = [
    219     ('index', 'pygresql', u'PyGreSQL Documentation',
    220      [u'The PyGreSQL team'], 1)
     256    (master_doc, 'pygresql', 'PyGreSQL Documentation', [author], 1)
    221257]
    222258
     
    225261
    226262
    227 # -- Options for Texinfo output ------------------------------------------------
     263# -- Options for Texinfo output -------------------------------------------
    228264
    229265# Grouping the document tree into Texinfo files. List of tuples
     
    231267#  dir menu entry, description, category)
    232268texinfo_documents = [
    233   ('index', 'PyGreSQL', u'PyGreSQL Documentation',
    234    u'The PyGreSQL team', 'PyGreSQL', 'One line description of project.',
    235    'Miscellaneous'),
     269    (master_doc, 'PyGreSQL', u'PyGreSQL Documentation',
     270     author, 'PyGreSQL', 'One line description of project.',
     271     'Miscellaneous'),
    236272]
    237273
     
    244280# How to display URL addresses: 'footnote', 'no', or 'inline'.
    245281#texinfo_show_urls = 'footnote'
     282
     283# If true, do not generate a @detailmenu in the "Top" node's menu.
     284#texinfo_no_detailmenu = False
  • trunk/docs/make.bat

    r516 r669  
    3434        echo.  gettext    to make PO message catalogs
    3535        echo.  changes    to make an overview over all changed/added/deprecated items
     36        echo.  xml        to make Docutils-native XML files
     37        echo.  pseudoxml  to make pseudoxml-XML files for display purposes
    3638        echo.  linkcheck  to check all external links for integrity
    3739        echo.  doctest    to run all doctests embedded in the documentation if enabled
     40        echo.  coverage   to run coverage check of the documentation if enabled
    3841        goto end
    3942)
     
    4447        goto end
    4548)
     49
     50
     51REM Check if sphinx-build is available and fallback to Python version if any
     52%SPHINXBUILD% 1>NUL 2>NUL
     53if errorlevel 9009 goto sphinx_python
     54goto sphinx_ok
     55
     56:sphinx_python
     57
     58set SPHINXBUILD=python -m sphinx.__init__
     59%SPHINXBUILD% 2> nul
     60if errorlevel 9009 (
     61        echo.
     62        echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
     63        echo.installed, then set the SPHINXBUILD environment variable to point
     64        echo.to the full path of the 'sphinx-build' executable. Alternatively you
     65        echo.may add the Sphinx directory to PATH.
     66        echo.
     67        echo.If you don't have Sphinx installed, grab it from
     68        echo.http://sphinx-doc.org/
     69        exit /b 1
     70)
     71
     72:sphinx_ok
     73
    4674
    4775if "%1" == "html" (
     
    130158)
    131159
     160if "%1" == "latexpdf" (
     161        %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
     162        cd %BUILDDIR%/latex
     163        make all-pdf
     164        cd %~dp0
     165        echo.
     166        echo.Build finished; the PDF files are in %BUILDDIR%/latex.
     167        goto end
     168)
     169
     170if "%1" == "latexpdfja" (
     171        %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
     172        cd %BUILDDIR%/latex
     173        make all-pdf-ja
     174        cd %~dp0
     175        echo.
     176        echo.Build finished; the PDF files are in %BUILDDIR%/latex.
     177        goto end
     178)
     179
    132180if "%1" == "text" (
    133181        %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
     
    188236)
    189237
     238if "%1" == "coverage" (
     239        %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
     240        if errorlevel 1 exit /b 1
     241        echo.
     242        echo.Testing of coverage in the sources finished, look at the ^
     243results in %BUILDDIR%/coverage/python.txt.
     244        goto end
     245)
     246
     247if "%1" == "xml" (
     248        %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
     249        if errorlevel 1 exit /b 1
     250        echo.
     251        echo.Build finished. The XML files are in %BUILDDIR%/xml.
     252        goto end
     253)
     254
     255if "%1" == "pseudoxml" (
     256        %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
     257        if errorlevel 1 exit /b 1
     258        echo.
     259        echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
     260        goto end
     261)
     262
    190263:end
Note: See TracChangeset for help on using the changeset viewer.