mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Update sphinx-quickstart man page
This man page wasn't making full use of Sphinx's own features. Update it to do so, and remove the duplicated information from 'invocation'. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
parent
c244a7c9a9
commit
2cfa2bc673
@ -5,172 +5,7 @@
|
||||
Invocation of sphinx-quickstart
|
||||
===============================
|
||||
|
||||
The :program:`sphinx-quickstart` script generates a Sphinx documentation set.
|
||||
It is called like this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sphinx-quickstart [options] [projectdir]
|
||||
|
||||
where *projectdir* is the Sphinx documentation set directory in which you want
|
||||
to place. If you omit *projectdir*, files are generated into current directory
|
||||
by default.
|
||||
|
||||
The :program:`sphinx-quickstart` script has several options:
|
||||
|
||||
.. program:: sphinx-quickstart
|
||||
|
||||
.. option:: -q, --quiet
|
||||
|
||||
Quiet mode that will skips interactive wizard to specify options.
|
||||
This option requires `-p`, `-a` and `-v` options.
|
||||
|
||||
.. option:: -h, --help, --version
|
||||
|
||||
Display usage summary or Sphinx version.
|
||||
|
||||
|
||||
Structure options
|
||||
-----------------
|
||||
|
||||
.. option:: --sep
|
||||
|
||||
If specified, separate source and build directories.
|
||||
|
||||
.. option:: --dot=DOT
|
||||
|
||||
Inside the root directory, two more directories will be created;
|
||||
"_templates" for custom HTML templates and "_static" for custom stylesheets
|
||||
and other static files. You can enter another prefix (such as ".") to
|
||||
replace the underscore.
|
||||
|
||||
Project basic options
|
||||
---------------------
|
||||
|
||||
.. option:: -p PROJECT, --project=PROJECT
|
||||
|
||||
Project name will be set. (see :confval:`project`).
|
||||
|
||||
.. option:: -a AUTHOR, --author=AUTHOR
|
||||
|
||||
Author names. (see :confval:`copyright`).
|
||||
|
||||
.. option:: -v VERSION
|
||||
|
||||
Version of project. (see :confval:`version`).
|
||||
|
||||
.. option:: -r RELEASE, --release=RELEASE
|
||||
|
||||
Release of project. (see :confval:`release`).
|
||||
|
||||
.. option:: -l LANGUAGE, --language=LANGUAGE
|
||||
|
||||
Document language. (see :confval:`language`).
|
||||
|
||||
.. option:: --suffix=SUFFIX
|
||||
|
||||
Source file suffix. (see :confval:`source_suffix`).
|
||||
|
||||
.. option:: --master=MASTER
|
||||
|
||||
Master document name. (see :confval:`master_doc`).
|
||||
|
||||
.. option:: --epub
|
||||
|
||||
Use epub.
|
||||
|
||||
Extension options
|
||||
-----------------
|
||||
|
||||
.. option:: --ext-autodoc
|
||||
|
||||
Enable `sphinx.ext.autodoc` extension.
|
||||
|
||||
.. option:: --ext-doctest
|
||||
|
||||
Enable `sphinx.ext.doctest` extension.
|
||||
|
||||
.. option:: --ext-intersphinx
|
||||
|
||||
Enable `sphinx.ext.intersphinx` extension.
|
||||
|
||||
.. option:: --ext-todo
|
||||
|
||||
Enable `sphinx.ext.todo` extension.
|
||||
|
||||
.. option:: --ext-coverage
|
||||
|
||||
Enable `sphinx.ext.coverage` extension.
|
||||
|
||||
.. option:: --ext-imgmath
|
||||
|
||||
Enable `sphinx.ext.imgmath` extension.
|
||||
|
||||
.. option:: --ext-mathjax
|
||||
|
||||
Enable `sphinx.ext.mathjax` extension.
|
||||
|
||||
.. option:: --ext-ifconfig
|
||||
|
||||
Enable `sphinx.ext.ifconfig` extension.
|
||||
|
||||
.. option:: --ext-viewcode
|
||||
|
||||
Enable `sphinx.ext.viewcode` extension.
|
||||
|
||||
.. option:: --extensions=EXTENSIONS
|
||||
|
||||
Enable arbitary extensions.
|
||||
|
||||
|
||||
Makefile and Batchfile creation options
|
||||
---------------------------------------
|
||||
|
||||
.. option:: --use-make-mode, --no-use-make-mode
|
||||
|
||||
Makefile/make.bat uses (or not use) make-mode. Default is use.
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
make-mode is default.
|
||||
|
||||
.. option:: --makefile, --no-makefile
|
||||
|
||||
Create (or not create) makefile.
|
||||
|
||||
.. option:: --batchfile, --no-batchfile
|
||||
|
||||
Create (or not create) batchfile
|
||||
|
||||
|
||||
.. versionadded:: 1.3
|
||||
Add various options for sphinx-quickstart invocation.
|
||||
|
||||
Project templating
|
||||
------------------
|
||||
|
||||
.. option:: -t, --templatedir=TEMPLATEDIR
|
||||
|
||||
Template directory for template files. You can modify the templates of
|
||||
sphinx project files generated by quickstart. Following Jinja2 template
|
||||
files are allowed:
|
||||
|
||||
* master_doc.rst_t
|
||||
* conf.py_t
|
||||
* Makefile_t
|
||||
* Makefile.new_t
|
||||
* make.bat_t
|
||||
* make.bat.new_t
|
||||
|
||||
In detail, please refer the system template files Sphinx provides.
|
||||
(sphinx/templates/quickstart)
|
||||
|
||||
.. option:: -d NAME=VALUE
|
||||
|
||||
Define a template variable
|
||||
|
||||
.. versionadded:: 1.5
|
||||
Project templating options for sphinx-quickstart
|
||||
|
||||
Refer to the :doc:`sphinx-quickstart man page <man/sphinx-quickstart>`.
|
||||
|
||||
Invocation of sphinx-build
|
||||
==========================
|
||||
@ -437,8 +272,6 @@ variable to your environment. For example:
|
||||
* modify your Makefile/make.bat and set the environment variable
|
||||
|
||||
|
||||
.. _invocation-apidoc:
|
||||
|
||||
Invocation of sphinx-apidoc
|
||||
===========================
|
||||
|
||||
|
||||
@ -1,14 +1,11 @@
|
||||
:orphan:
|
||||
|
||||
sphinx-quickstart manual page
|
||||
=============================
|
||||
sphinx-quickstart
|
||||
=================
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
**sphinx-quickstart**
|
||||
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
@ -16,13 +13,156 @@ Description
|
||||
about your project and then generates a complete documentation directory and
|
||||
sample Makefile to be used with :manpage:`sphinx-build(1)`.
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
.. program:: sphinx-quickstart
|
||||
|
||||
.. option:: -q, --quiet
|
||||
|
||||
Quiet mode that will skips interactive wizard to specify options.
|
||||
This option requires `-p`, `-a` and `-v` options.
|
||||
|
||||
.. option:: -h, --help, --version
|
||||
|
||||
Display usage summary or Sphinx version.
|
||||
|
||||
.. rubric:: Structure Options
|
||||
|
||||
.. option:: --sep
|
||||
|
||||
If specified, separate source and build directories.
|
||||
|
||||
.. option:: --dot=DOT
|
||||
|
||||
Inside the root directory, two more directories will be created;
|
||||
"_templates" for custom HTML templates and "_static" for custom stylesheets
|
||||
and other static files. You can enter another prefix (such as ".") to
|
||||
replace the underscore.
|
||||
|
||||
.. rubric:: Project Basic Options
|
||||
|
||||
.. option:: -p PROJECT, --project=PROJECT
|
||||
|
||||
Project name will be set. (see :confval:`project`).
|
||||
|
||||
.. option:: -a AUTHOR, --author=AUTHOR
|
||||
|
||||
Author names. (see :confval:`copyright`).
|
||||
|
||||
.. option:: -v VERSION
|
||||
|
||||
Version of project. (see :confval:`version`).
|
||||
|
||||
.. option:: -r RELEASE, --release=RELEASE
|
||||
|
||||
Release of project. (see :confval:`release`).
|
||||
|
||||
.. option:: -l LANGUAGE, --language=LANGUAGE
|
||||
|
||||
Document language. (see :confval:`language`).
|
||||
|
||||
.. option:: --suffix=SUFFIX
|
||||
|
||||
Source file suffix. (see :confval:`source_suffix`).
|
||||
|
||||
.. option:: --master=MASTER
|
||||
|
||||
Master document name. (see :confval:`master_doc`).
|
||||
|
||||
.. option:: --epub
|
||||
|
||||
Use epub.
|
||||
|
||||
.. rubric:: Extension Options
|
||||
|
||||
.. option:: --ext-autodoc
|
||||
|
||||
Enable `sphinx.ext.autodoc` extension.
|
||||
|
||||
.. option:: --ext-doctest
|
||||
|
||||
Enable `sphinx.ext.doctest` extension.
|
||||
|
||||
.. option:: --ext-intersphinx
|
||||
|
||||
Enable `sphinx.ext.intersphinx` extension.
|
||||
|
||||
.. option:: --ext-todo
|
||||
|
||||
Enable `sphinx.ext.todo` extension.
|
||||
|
||||
.. option:: --ext-coverage
|
||||
|
||||
Enable `sphinx.ext.coverage` extension.
|
||||
|
||||
.. option:: --ext-imgmath
|
||||
|
||||
Enable `sphinx.ext.imgmath` extension.
|
||||
|
||||
.. option:: --ext-mathjax
|
||||
|
||||
Enable `sphinx.ext.mathjax` extension.
|
||||
|
||||
.. option:: --ext-ifconfig
|
||||
|
||||
Enable `sphinx.ext.ifconfig` extension.
|
||||
|
||||
.. option:: --ext-viewcode
|
||||
|
||||
Enable `sphinx.ext.viewcode` extension.
|
||||
|
||||
.. option:: --extensions=EXTENSIONS
|
||||
|
||||
Enable arbitary extensions.
|
||||
|
||||
.. rubric:: Makefile and Batchfile Creation Options
|
||||
|
||||
.. option:: --use-make-mode, --no-use-make-mode
|
||||
|
||||
Makefile/make.bat uses (or not use) make-mode. Default is use.
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
make-mode is default.
|
||||
|
||||
.. option:: --makefile, --no-makefile
|
||||
|
||||
Create (or not create) makefile.
|
||||
|
||||
.. option:: --batchfile, --no-batchfile
|
||||
|
||||
Create (or not create) batchfile
|
||||
|
||||
.. rubric:: Project templating
|
||||
|
||||
.. versionadded:: 1.5
|
||||
Project templating options for sphinx-quickstart
|
||||
|
||||
.. option:: -t, --templatedir=TEMPLATEDIR
|
||||
|
||||
Template directory for template files. You can modify the templates of
|
||||
sphinx project files generated by quickstart. Following Jinja2 template
|
||||
files are allowed:
|
||||
|
||||
* ``master_doc.rst_t``
|
||||
* ``conf.py_t``
|
||||
* ``Makefile_t``
|
||||
* ``Makefile.new_t``
|
||||
* ``make.bat_t``
|
||||
* ``make.bat.new_t``
|
||||
|
||||
In detail, please refer the system template files Sphinx provides.
|
||||
(``sphinx/templates/quickstart``)
|
||||
|
||||
.. option:: -d NAME=VALUE
|
||||
|
||||
Define a template variable
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
:manpage:`sphinx-build(1)`
|
||||
|
||||
|
||||
Author
|
||||
------
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ configuration values from a few questions it asks you. Just run ::
|
||||
and answer its questions. (Be sure to say yes to the "autodoc" extension.)
|
||||
|
||||
There is also an automatic "API documentation" generator called
|
||||
:program:`sphinx-apidoc`; see :ref:`invocation-apidoc` for details.
|
||||
:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details.
|
||||
|
||||
|
||||
Defining document structure
|
||||
|
||||
Loading…
Reference in New Issue
Block a user