[Python-modules-commits] r14302 - in packages/sphinx/trunk/debian (changelog sphinx-build.1)

Sun Aug 29 12:12:29 UTC 2010

Date: Sunday, August 29, 2010 @ 12:12:04
  Author: jwilk
Revision: 14302

Update and significantly rewrite the sphinx-build manual page.

Modified:
  packages/sphinx/trunk/debian/changelog
  packages/sphinx/trunk/debian/sphinx-build.1

Modified: packages/sphinx/trunk/debian/changelog
===================================================================

--- packages/sphinx/trunk/debian/changelog	2010-08-29 10:14:19 UTC (rev 14301)
+++ packages/sphinx/trunk/debian/changelog	2010-08-29 12:12:04 UTC (rev 14302)
@@ -2,8 +2,10 @@
 
   * Add myself to uploaders.
   * Fix formatting of the manual pages.
+  * Update and significantly rewrite the sphinx-build manual page
+    (closes: #593623).
 
- -- Jakub Wilk <jwilk at debian.org>  Mon, 23 Aug 2010 20:29:12 +0200
+ -- Jakub Wilk <jwilk at debian.org>  Sun, 29 Aug 2010 14:09:21 +0200
 
 sphinx (0.6.6-2) unstable; urgency=low
 

Modified: packages/sphinx/trunk/debian/sphinx-build.1
===================================================================
--- packages/sphinx/trunk/debian/sphinx-build.1	2010-08-29 10:14:19 UTC (rev 14301)
+++ packages/sphinx/trunk/debian/sphinx-build.1	2010-08-29 12:12:04 UTC (rev 14302)
@@ -1,4 +1,4 @@
-.TH sphinx-build 1 "Apr 2008" "Sphinx 0.1.61950" "User Commands"
+.TH sphinx-build 1 "Aug 2010" "Sphinx 0.6.6" "User Commands"
 .SH NAME
 sphinx-build \- Sphinx documentation generator tool
 .SH SYNOPSIS
@@ -19,50 +19,80 @@
 List of available builders:
 .TP
 \fBhtml\fR
-HTML files generation. This is default builder.
+Build HTML pages. This is the default builder.
 .TP
-\fBweb\fR
-Generating files for sphinx-web (currently undergo the full rewrite, and not working).
+\fBdirhtml\fR
+Build HTML pages, but with a single directory per document.
 .TP
-\fBhtmlhelp\fR
-Generates files for CHM generation.
+\fBhtmlhelp\fR, \fBqthelp\fR
+Build HTML pages with additional information for building a documentation collection in one of these formats.
 .TP
 \fBlatex\fR
-Generates LaTeX version of documentation. This builder uses PAPER environment variable (e.g. PAPER=a4 or PAPER=letter) if available.
+Build LaTeX sources that can be compiled to a PDF document using \fBpdflatex\fR.
+This builder uses the PAPER environment variable (e.g. PAPER=a4 or PAPER=letter) if available.
 .TP
+\fBtext\fR
+Build plain text files.
+.TP
 \fBchanges\fR
-Shows changed/added/deprecated items since last documentation generation.
+Show changed/added/deprecated items since last documentation generation.
 .TP
 \fBlinkcheck\fR
-Checks the integrity of all external links in documentation
+Check the integrity of all external links in documentation.
+.TP
+\fBpickle\fR, \fBjson\fR
+Produce a directory with pickle/JSON files containing mostly HTML fragments and TOC information, for use of a web application (or a custom postprocessing tool) that doesn't use the standard HTML templates.
 .SH OPTIONS
 .TP
 \fB-b\fR \fIbuilder\fR
-Builder to use; defaults to html. See the full list of builders above.
+Select a builder. The default is \fBhtml\fR. See the full list of builders above.
 .TP
 \fIfilename\fR
-Force to generate documentation for the file
+Force to generate documentation for the file.
 .TP
 \fB-a\fR
-Generate all files; without this option only documentation for new and changed files is generated
+Always write all output files.
+(The default is to only write output files for new and changed source files.)
 .TP
 \fB-E\fR
-Ignore cached files, forces to re-read all files from disk.
+Don't use a saved environment, but rebuild it completely.
+(The default is to only read and parse source files that are new or have changed since the last run.)
 .TP
+\fB-t\fR \fItag\fR
+Define the \fItag\fR. This is relevant for \[oq\]only\[cq\] directives that only include their content if this tag is set.
+.TP
 \fB-d\fR \fIpath\fR
-Path to cached environment; defaults to \fIoutdir\fP/.doctrees
+Select cache directory. The default is \fIoutdir\fP/.doctrees/.
 .TP
+\fB-c\fR \fIpath\fR
+Don't look for the conf.py in the \fIsourcedir\fR, but use the given configuration directory instead. Various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.
+.TP
+\fB-C\fR
+Don't look for a configuration file; only take options via the \fB-D\fR option.
+.TP
 \fB-D\fR \fIsetting\fR=\fIvalue\fR
-Overrides setting from \fIsourcedir\fR/conf.py
+Override a configuration value set in the \fBconf.py\fR file.
 .TP
+\fB-A\fR \fIname\fR=\fIvalue\fR
+Make the \fIname\fR assigned to \fIvalue\fR in the HTML templates.
+.TP
 \fB-N\fR
-Do not do colored output
+Do not emit colored output
 .TP
 \fB-q\fR
-Quiet operation, just prints warnings and errors on stderr
+Do not output anything on standard output, only write warnings and errors to standard error.
 .TP
+\fB-Q\fR
+Do not output anything on standard output, also suppress warnings. Only errors are written to standard error.
+.TP
+\fB-w\fR \fIfile\fR
+Write warnings (and errors) to the given file, in addition to standard error.
+.TP
+\fB-W\fR
+Turn warnings into errors. This means that the build stops at the first warning and \fBsphinx-build\fR exits with exit status 1.
+.TP
 \fB-P\fR
-Run Pdb on exception
+Run the Python debugger, \fBpdb\fR, if an unhandled exception occurs while building.
 .SH "SEE ALSO"
 \fBsphinx-quickstart\fR(1)
 .PP


