[Python-modules-commits] r14309 - in packages/sphinx/branches/1.0/debian (4 files)

Mon Aug 30 16:13:56 UTC 2010

Date: Monday, August 30, 2010 @ 16:13:39
  Author: jwilk
Revision: 14309

Merge manpage updates from the 0.6 branch.

Modified:
  packages/sphinx/branches/1.0/debian/changelog
  packages/sphinx/branches/1.0/debian/sphinx-autogen.1
  packages/sphinx/branches/1.0/debian/sphinx-build.1
  packages/sphinx/branches/1.0/debian/sphinx-quickstart.1

Modified: packages/sphinx/branches/1.0/debian/changelog
===================================================================

--- packages/sphinx/branches/1.0/debian/changelog	2010-08-30 16:03:28 UTC (rev 14308)
+++ packages/sphinx/branches/1.0/debian/changelog	2010-08-30 16:13:39 UTC (rev 14309)
@@ -1,8 +1,11 @@
 sphinx (1.0.3-1) UNRELEASED; urgency=low
 
   * New upstream release.
+  * Fix formatting of the manual pages.
+  * Update and significantly rewrite the sphinx-build manual page
+    (closes: #593623).
 
- -- Jakub Wilk <jwilk at debian.org>  Mon, 30 Aug 2010 18:00:02 +0200
+ -- Jakub Wilk <jwilk at debian.org>  Mon, 30 Aug 2010 18:10:56 +0200
 
 sphinx (1.0.1-1) experimental; urgency=low
 

Modified: packages/sphinx/branches/1.0/debian/sphinx-autogen.1
===================================================================
--- packages/sphinx/branches/1.0/debian/sphinx-autogen.1	2010-08-30 16:03:28 UTC (rev 14308)
+++ packages/sphinx/branches/1.0/debian/sphinx-autogen.1	2010-08-30 16:13:39 UTC (rev 14309)
@@ -6,16 +6,16 @@
 
 .SH SYNOPSIS
 .B sphinx\-autogen
-[\fI\-o output_dir\fR]
-[\fI\-s suffix\fR]
+[\-o \fIoutput_dir\fR]
+[\-s \fIsuffix\fR]
 .BI sourcefile ...
 
 .SH OPTIONS
 .TP
-\fB\-o output_dir\fR
+\fB\-o \fIoutput_dir\fR
 the directory the output files should be written to
 .TP
-\fB\-s suffix\fR
+\fB\-s \fIsuffix\fR
 the suffix of the written files (defaults to rst)
 
 .SH DESCRIPTION
@@ -31,8 +31,8 @@
 .I sphinx.ext.autosummary
 
 .SH SEE ALSO
-.BR sphinx\-quickstart (1),
-.BR sphinx\-build (1)
+\fBsphinx\-quickstart\fR(1),
+\fBsphinx\-build\fR(1)
 
 .mso www.tmac
 .URL "http://sphinx.pocoo.org/" "The Sphinx website"

Modified: packages/sphinx/branches/1.0/debian/sphinx-build.1
===================================================================
--- packages/sphinx/branches/1.0/debian/sphinx-build.1	2010-08-30 16:03:28 UTC (rev 14308)
+++ packages/sphinx/branches/1.0/debian/sphinx-build.1	2010-08-30 16:13:39 UTC (rev 14309)
@@ -1,71 +1,101 @@
-.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
 .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
-to the <outdir>.
+\fBsphinx-build\fR generates documentation from the files in \fIsourcedir\fR and places it
+to the \fIoutdir\fR.
 
-sphinx-build looks for <sourcedir>/conf.py for the configuration settings.
-.B sphinx-quickstart(1)
+\fBsphinx-build\fR looks for \fIsourcedir\fR/conf.py for the configuration settings.
+\fBsphinx-quickstart\fR(1)
 may be used to generate template files, including conf.py.
 
-sphinx-build can create documentation in different formats. Format is selected
+\fBsphinx-build\fR can create documentation in different formats. Format is selected
 by specifying builder in command line and defaults to HTML. Builders can
 also perform other tasks related to the documentation processing.
 
 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 <builder>
-Builder to use; defaults to html. See the full list of builders above.
+\fB-b\fR \fIbuilder\fR
+Select a builder. The default is \fBhtml\fR. See the full list of builders above.
 .TP
-\fB<filename>\fR
-Force to generate documentation for the file
+\fIfilename\fR
+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-d\fR <path>
-Path to cached environment; defaults to <outdir>/.doctrees
+\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 <setting>=<value>
-Overrides setting from <sourcedir>/conf.py
+\fB-d\fR \fIpath\fR
+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
+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"
-.BR sphinx-quickstart(1)
-.br
+\fBsphinx-quickstart\fR(1)
+.PP
 The full documentation for
 .B Sphinx
 is installed to

Modified: packages/sphinx/branches/1.0/debian/sphinx-quickstart.1
===================================================================
--- packages/sphinx/branches/1.0/debian/sphinx-quickstart.1	2010-08-30 16:03:28 UTC (rev 14308)
+++ packages/sphinx/branches/1.0/debian/sphinx-quickstart.1	2010-08-30 16:13:39 UTC (rev 14309)
@@ -6,10 +6,10 @@
 .SH DESCRIPTION
 sphinx-quickstart is the interactive tool which asks some questions about your
 Python project and then generates template documentation directory and sample
-Makefile to be used with \fBsphinx-build(1)\fR.
+Makefile to be used with \fBsphinx-build\fR(1).
 .SH "SEE ALSO"
-.BR sphinx-build(1)
-.br
+\fBsphinx-build\fR(1)
+.PP
 The full documentation for
 .B Sphinx
 is installed to


