IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Remove hand-written manpages, add rst documents to be built with the manpage builder.

Browse Source
This commit is contained in:
Georg Brandl
2010-02-25 22:22:01 +01:00
parent 5c92da1c12
commit 07a658e50c
5 changed files with 135 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/conf.py
View File

@@ -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),
]

101
doc/man/sphinx-build.rst Normal file
View File

@@ -0,0 +1,101 @@
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.

30
doc/man/sphinx-quickstart.rst Normal file
View File

@@ -0,0 +1,30 @@
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.

105
doc/sphinx-build.1
View File

@@ -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.

17
doc/sphinx-quickstart.1
View File

@@ -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.