diff --git a/doc/Makefile b/doc/Makefile index 153a93dba..a8897d2be 100644 --- a/doc/Makefile +++ b/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 ' where is one of" diff --git a/doc/conf.py b/doc/conf.py index b1a55b0e4..24cf5f3cd 100644 --- a/doc/conf.py +++ b/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), ] diff --git a/doc/config.rst b/doc/config.rst index 917bdf144..21b0134dd 100644 --- a/doc/config.rst +++ b/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. diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst new file mode 100644 index 000000000..ca493ec00 --- /dev/null +++ b/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 +```` and places it in the ````. + +:program:`sphinx-build` looks for ``/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 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 Locates the conf.py file in the specified path instead of + . +-C Specifies that no conf.py file at all is to be used. + Configuration can only be set with the -D option. +-D Overrides a setting from the configuration file. +-d Path to cached files; defaults to /.doctrees. +-A 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 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 , Armin Ronacher et +al. + +This manual page was initially written by Mikhail Gusarov +, for the Debian project. diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst new file mode 100644 index 000000000..172772610 --- /dev/null +++ b/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 , Armin Ronacher et +al. + +This manual page was initially written by Mikhail Gusarov +, for the Debian project. diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 01e5a3f18..7db403ab8 100644 --- a/doc/markup/misc.rst +++ b/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 ----------------------- diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1 deleted file mode 100644 index a3df16d03..000000000 --- a/doc/sphinx-build.1 +++ /dev/null @@ -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 and places it -in the . - -sphinx-build looks for /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 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 -Locates the conf.py file in the specified path instead of . -.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 = -Overrides a setting from the configuration file. -.TP -\fB-d\fR -Path to cached files; defaults to /.doctrees. -.TP -\fB-A\fR = -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 -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 , Armin Ronacher et -al. -.PP -This manual page was initially written by Mikhail Gusarov -, for the Debian project. diff --git a/doc/sphinx-quickstart.1 b/doc/sphinx-quickstart.1 deleted file mode 100644 index 93b0a4a51..000000000 --- a/doc/sphinx-quickstart.1 +++ /dev/null @@ -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 , Armin Ronacher et -al. -.PP -This manual page was initially written by Mikhail Gusarov - for the Debian project. diff --git a/sphinx/builders/manpage.py b/sphinx/builders/manpage.py index fa795a155..756e4732f 100644 --- a/sphinx/builders/manpage.py +++ b/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) diff --git a/sphinx/environment.py b/sphinx/environment.py index dacec2c11..ad6d6ea8b 100644 --- a/sphinx/environment.py +++ b/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') diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 87513eb21..f42e3e11e 100644 --- a/sphinx/quickstart.py +++ b/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 ' where is one of" diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 325d5001d..eb35c5a53 100644 --- a/sphinx/writers/manpage.py +++ b/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])