merge

doc/Makefile

@@ -11,7 +11,7 @@ PAPEROPT_letter  = -D latex_paper_size=letter
 ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest man
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"

doc/conf.py

@@ -52,6 +52,10 @@ todo_include_todos = True
 man_pages = [
     ('contents', 'sphinx-all', 'Sphinx documentation generator system manual',
      'Georg Brandl', 1),
+    ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
+     '', 1),
+    ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
+     'template generator', '', 1),
 ]
 
 

doc/config.rst

@@ -935,7 +935,9 @@ These options influence manual page output.
      well as the name of the manual page (in the NAME section).
    * *description*: description of the manual page.  This is used in the NAME
      section.
-   * *authors*: A list of strings with authors, or a single string.
+   * *authors*: A list of strings with authors, or a single string.  Can be
+     an empty string or list if you do not want to automatically generate
+     an AUTHORS section in the manual page.
    * *section*: The manual page section.  Used for the output file name as well
      as in the manual page header.
 

doc/man/sphinx-build.rst

@@ -0,0 +1,102 @@
+:orphan:
+
+sphinx-build manual page
+========================
+
+Synopsis
+--------
+
+**sphinx-build** [*options*] <*sourcedir*> <*outdir*> [*filenames* ...]
+
+
+Description
+-----------
+
+:program:`sphinx-build` generates documentation from the files in
+``<sourcedir>`` and places it in the ``<outdir>``.
+
+:program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration
+settings.  :manpage:`sphinx-quickstart(1)` may be used to generate template
+files, including ``conf.py``.
+
+:program:`sphinx-build` can create documentation in different formats.  A format
+is selected by specifying the builder name on the command line; it defaults to
+HTML.  Builders can also perform other tasks related to documentation
+processing.
+
+By default, everything that is outdated is built.  Output only for selected
+files can be built by specifying individual filenames.
+
+List of available builders:
+
+html
+   HTML file generation.  This is the default builder.
+
+htmlhelp
+   Generates files for CHM (compiled help files) generation.
+
+qthelp
+   Generates files for Qt help collection generation.
+
+devhelp
+   Generates files for the GNOME Devhelp help viewer.
+
+latex
+   Generates LaTeX output that can be compiled to a PDF document.
+
+man
+   Generates manual pages.
+
+text
+   Generates a plain-text version of the documentation.
+
+changes
+   Generates HTML files listing changed/added/deprecated items for
+   the current version of the documented project.
+
+linkcheck
+   Checks the integrity of all external links in the source.
+
+pickle / json
+   Generates serialized HTML files for use in web applications.
+
+
+Options
+-------
+
+-b <builder>          Builder to use; defaults to html. See the full list
+                      of builders above.
+-a                    Generates output for all files; without this option only
+                      output for new and changed files is generated.
+-E                    Ignores cached files, forces to re-read all source files
+                      from disk.
+-c <path>             Locates the conf.py file in the specified path instead of
+                      <sourcedir>.
+-C                    Specifies that no conf.py file at all is to be used.
+                      Configuration can only be set with the -D option.
+-D <setting=value>    Overrides a setting from the configuration file.
+-d <path>             Path to cached files; defaults to <outdir>/.doctrees.
+-A <name=value>       Passes a value into the HTML templates (only for HTML builders).
+-N                    Prevents colored output.
+-q                    Quiet operation, just prints warnings and errors on stderr.
+-Q                    Very quiet operation, doesn't print anything except for
+                      errors.
+-w <file>             Write warnings and errors into the given file, in addition
+                      to stderr.
+-W                    Turn warnings into errors.
+-P                    Runs Pdb on exception.
+
+
+See also
+--------
+
+:manpage:`sphinx-quickstart(1)`
+
+Author
+------
+
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net>, for the Debian project.

doc/man/sphinx-quickstart.rst

@@ -0,0 +1,33 @@
+:orphan:
+
+sphinx-quickstart manual page
+=============================
+
+Synopsis
+--------
+
+**sphinx-quickstart**
+
+
+Description
+-----------
+
+:program:`sphinx-quickstart` is an interactive tool that asks some questions
+about your project and then generates a complete documentation directory and
+sample Makefile to be used with :manpage:`sphinx-build(1)`.
+
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`
+
+
+Author
+------
+
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net>, for the Debian project.

doc/markup/misc.rst

@@ -29,6 +29,12 @@ At the moment, these metadata fields are recognized:
    If set, the web application won't display a comment form for a page generated
    from this source file.
 
+``orphan``
+   If set, warnings about this file not being included in any toctree will be
+   suppressed.
+
+   .. versionadded:: 1.0
+
 
 Meta-information markup
 -----------------------

doc/sphinx-build.1

@@ -1,105 +0,0 @@
-.TH sphinx-build 1 "Jan 2009" "Sphinx 0.6" "User Commands"
-.SH NAME
-sphinx-build \- Sphinx documentation generator tool
-.SH SYNOPSIS
-.B sphinx-build
-[\fIoptions\fR] <\fIsourcedir\fR> <\fIoutdir\fR> [\fIfilenames\fR...]
-.SH DESCRIPTION
-sphinx-build generates documentation from the files in <sourcedir> and places it
-in the <outdir>.
-
-sphinx-build looks for <sourcedir>/conf.py for the configuration settings.
-.B sphinx-quickstart(1)
-may be used to generate template files, including conf.py.
-
-sphinx-build can create documentation in different formats.  A format is
-selected by specifying the builder name on the command line; it defaults to
-HTML.  Builders can also perform other tasks related to documentation
-processing.
-
-By default, everything that is outdated is built.  Output only for selected
-files can be built by specifying individual filenames.
-
-List of available builders:
-.TP
-\fBhtml\fR
-HTML files generation.  This is default builder.
-.TP
-\fBhtmlhelp\fR
-Generates files for CHM generation.
-.TP
-\fBqthelp\fR
-Generates files for Qt help collection generation.
-.TP
-\fBdevhelp\fR
-Generates files for GNOME Devhelp help viewer.
-.TP
-\fBlatex\fR
-Generates a LaTeX version of the documentation.
-.TP
-\fBtext\fR
-Generates a plain-text version of the documentation.
-.TP
-\fBchanges\fR
-Generates HTML files listing changed/added/deprecated items for the
-current version.
-.TP
-\fBlinkcheck\fR
-Checks the integrity of all external links in the documentation.
-.TP
-\fBpickle / json\fR
-Generates serialized HTML files in the selected format.
-
-.SH OPTIONS
-.TP
-\fB-b\fR <builder>
-Builder to use; defaults to html. See the full list of builders above.
-.TP
-\fB-a\fR
-Generates output for all files; without this option only output for
-new and changed files is generated.
-.TP
-\fB-E\fR
-Ignores cached files, forces to re-read all source files from disk.
-.TP
-\fB-c\fR <path>
-Locates the conf.py file in the specified path instead of <sourcedir>.
-.TP
-\fB-C\fR
-Specifies that no conf.py file at all is to be used.  Configuration can
-only be set with the -D option.
-.TP
-\fB-D\fR <setting>=<value>
-Overrides a setting from the configuration file.
-.TP
-\fB-d\fR <path>
-Path to cached files; defaults to <outdir>/.doctrees.
-.TP
-\fB-A\fR <name>=<value>
-Passes a value into the HTML templates (only for html builders).
-.TP
-\fB-N\fR
-Prevents colored output.
-.TP
-\fB-q\fR
-Quiet operation, just prints warnings and errors on stderr.
-.TP
-\fB-Q\fR
-Very quiet operation, doesn't print anything except for errors.
-.TP
-\fB-w\fR <file>
-Write warnings and errors into the given file, in addition to stderr.
-.TP
-\fB-W\fR
-Turn warnings into errors.
-.TP
-\fB-P\fR
-Runs Pdb on exception.
-.SH "SEE ALSO"
-.BR sphinx-quickstart(1)
-.SH AUTHOR
-Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
-al.
-.PP
-This manual page was initially written by Mikhail Gusarov
-<dottedmag@dottedmag.net>, for the Debian project.

doc/sphinx-quickstart.1

@@ -1,17 +0,0 @@
-.TH sphinx-quickstart 1 "Jan 2009" "Sphinx 0.6" "User Commands"
-.SH NAME
-sphinx-quickstart \- Sphinx documentation template generator
-.SH SYNOPSIS
-.B sphinx-quickstart
-.SH DESCRIPTION
-sphinx-quickstart is an interactive tool that asks some questions about your
-project and then generates a complete documentation directory and sample
-Makefile to be used with \fBsphinx-build(1)\fR.
-.SH "SEE ALSO"
-.BR sphinx-build(1)
-.SH AUTHOR
-Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
-al.
-.PP
-This manual page was initially written by Mikhail Gusarov
-<dottedmag@dottedmag.net> for the Debian project.

sphinx/builders/manpage.py

@@ -58,7 +58,10 @@ class ManualPageBuilder(Builder):
         for info in self.config.man_pages:
             docname, name, description, authors, section = info
             if isinstance(authors, basestring):
-                authors = [authors]
+                if authors:
+                    authors = [authors]
+                else:
+                    authors = []
 
             targetname = '%s.%s' % (name, section)
             self.info(darkgreen(targetname) + ' { ', nonl=True)

sphinx/environment.py

@@ -1549,4 +1549,6 @@ class BuildEnvironment:
                 if docname == self.config.master_doc:
                     # the master file is not included anywhere ;)
                     continue
+                if 'orphan' in self.metadata[docname]:
+                    continue
                 self.warn(docname, 'document isn\'t included in any toctree')

sphinx/quickstart.py

@@ -320,8 +320,8 @@ PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) \
 $(SPHINXOPTS) %(rsrcdir)s
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp epub \
-latex changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp \
+epub latex latexpdf text man changes linkcheck doctest
 
 help:
 \t@echo "Please use \\`make <target>' where <target> is one of"

sphinx/writers/manpage.py

@@ -53,7 +53,9 @@ class ManualPageTranslator(BaseTranslator):
         # docinfo set by man_pages config value
         self._docinfo['title'] = self.document.settings.title
         self._docinfo['subtitle'] = self.document.settings.subtitle
-        self._docinfo['author'] = self.document.settings.authors
+        if self.document.settings.authors:
+            # don't set it if no author given
+            self._docinfo['author'] = self.document.settings.authors
         self._docinfo['manual_section'] = self.document.settings.section
 
         # docinfo set by other config values
@@ -221,6 +223,13 @@ class ManualPageTranslator(BaseTranslator):
     def depart_production(self, node):
         pass
 
+    # overwritten -- don't emit a warning for images
+    def visit_image(self, node):
+        if 'alt' in node.attributes:
+            self.body.append('[image: %s]\n' % node['alt'])
+        self.body.append('[image]\n')
+        raise nodes.SkipNode
+
     # overwritten -- don't visit inner marked up nodes
     def visit_reference(self, node):
         self.body.append(self.defs['reference'][0])