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
@@ -5,172 +5,7 @@
|
|||||||
Invocation of sphinx-quickstart
|
Invocation of sphinx-quickstart
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
The :program:`sphinx-quickstart` script generates a Sphinx documentation set.
|
Refer to the :doc:`sphinx-quickstart man page <man/sphinx-quickstart>`.
|
||||||
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
|
|
||||||
|
|
||||||
|
|
||||||
Invocation of sphinx-build
|
Invocation of sphinx-build
|
||||||
==========================
|
==========================
|
||||||
@@ -437,8 +272,6 @@ variable to your environment. For example:
|
|||||||
* modify your Makefile/make.bat and set the environment variable
|
* modify your Makefile/make.bat and set the environment variable
|
||||||
|
|
||||||
|
|
||||||
.. _invocation-apidoc:
|
|
||||||
|
|
||||||
Invocation of sphinx-apidoc
|
Invocation of sphinx-apidoc
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
|
|||||||
@@ -1,14 +1,11 @@
|
|||||||
:orphan:
|
sphinx-quickstart
|
||||||
|
=================
|
||||||
sphinx-quickstart manual page
|
|
||||||
=============================
|
|
||||||
|
|
||||||
Synopsis
|
Synopsis
|
||||||
--------
|
--------
|
||||||
|
|
||||||
**sphinx-quickstart**
|
**sphinx-quickstart**
|
||||||
|
|
||||||
|
|
||||||
Description
|
Description
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
@@ -16,13 +13,156 @@ Description
|
|||||||
about your project and then generates a complete documentation directory and
|
about your project and then generates a complete documentation directory and
|
||||||
sample Makefile to be used with :manpage:`sphinx-build(1)`.
|
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
|
See also
|
||||||
--------
|
--------
|
||||||
|
|
||||||
:manpage:`sphinx-build(1)`
|
:manpage:`sphinx-build(1)`
|
||||||
|
|
||||||
|
|
||||||
Author
|
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.)
|
and answer its questions. (Be sure to say yes to the "autodoc" extension.)
|
||||||
|
|
||||||
There is also an automatic "API documentation" generator called
|
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
|
Defining document structure
|
||||||
|
|||||||
Reference in New Issue
Block a user