From 2cfa2bc67371a229b8b1fa05fc69eb5e82efc61f Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 4 Jul 2017 20:03:05 +0100 Subject: [PATCH] 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 --- doc/invocation.rst | 169 +--------------------------------- doc/man/sphinx-quickstart.rst | 152 ++++++++++++++++++++++++++++-- doc/tutorial.rst | 2 +- 3 files changed, 148 insertions(+), 175 deletions(-) diff --git a/doc/invocation.rst b/doc/invocation.rst index 80616d0c9..2b0ae8bb7 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -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 `. 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 =========================== diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst index 172772610..7437dca06 100644 --- a/doc/man/sphinx-quickstart.rst +++ b/doc/man/sphinx-quickstart.rst @@ -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 ------ diff --git a/doc/tutorial.rst b/doc/tutorial.rst index ffabbd93e..20c5590e2 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -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