mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #7751 from stephenfin/doc/intro-section
[doc] Remove the intro guide in favour of the quickstart guide
This commit is contained in:
commit
350f5b3600
@ -1,4 +1,3 @@
|
||||
|
||||
.. _contents:
|
||||
|
||||
Sphinx documentation contents
|
||||
@ -7,26 +6,14 @@ Sphinx documentation contents
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro
|
||||
|
||||
usage/installation
|
||||
usage/quickstart
|
||||
usage/restructuredtext/index
|
||||
usage/markdown
|
||||
usage/configuration
|
||||
usage/builders/index
|
||||
usage/extensions/index
|
||||
usage/theming
|
||||
usage/advanced/intl
|
||||
usage/advanced/setuptools
|
||||
usage/advanced/websupport/index
|
||||
|
||||
usage/index
|
||||
development/index
|
||||
man/index
|
||||
|
||||
theming
|
||||
templating
|
||||
latex
|
||||
extdev/index
|
||||
development/tutorials/index
|
||||
|
||||
faq
|
||||
glossary
|
||||
|
13
doc/development/index.rst
Normal file
13
doc/development/index.rst
Normal file
@ -0,0 +1,13 @@
|
||||
================
|
||||
Extending Sphinx
|
||||
================
|
||||
|
||||
This guide is aimed at those wishing to develop their own extensions for
|
||||
Sphinx. Sphinx possesses significant extensibility capabilities including the
|
||||
ability to hook into almost every point of the build process. If you simply
|
||||
wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tutorials/index
|
23
doc/usage/index.rst
Normal file
23
doc/usage/index.rst
Normal file
@ -0,0 +1,23 @@
|
||||
============
|
||||
Using Sphinx
|
||||
============
|
||||
|
||||
This guide serves to demonstrate how one can get started with Sphinx and covers
|
||||
everything from installing Sphinx and configuring your first Sphinx project to
|
||||
using some of the advanced features Sphinx provides out-of-the-box. If you are
|
||||
looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
installation
|
||||
restructuredtext/index
|
||||
markdown
|
||||
configuration
|
||||
builders/index
|
||||
extensions/index
|
||||
theming
|
||||
advanced/intl
|
||||
advanced/setuptools
|
||||
advanced/websupport/index
|
@ -12,9 +12,13 @@ Installing Sphinx
|
||||
Overview
|
||||
--------
|
||||
|
||||
Sphinx is written in `Python`__ and supports Python 3.5+.
|
||||
Sphinx is written in `Python`__ and supports Python 3.5+. It builds upon the
|
||||
shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__,
|
||||
which are installed when Sphinx is installed.
|
||||
|
||||
__ https://docs.python-guide.org/
|
||||
__ https://docutils.sourceforge.io/
|
||||
__ https://jinja.palletsprojects.com/
|
||||
|
||||
|
||||
Linux
|
||||
|
@ -2,21 +2,38 @@
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
Once Sphinx is :doc:`installed </usage/installation>`, you can proceed with
|
||||
setting up your first Sphinx project. To ease the process of getting started,
|
||||
Sphinx provides a tool, :program:`sphinx-quickstart`, which will generate a
|
||||
documentation source directory and populate it with some defaults. We're going
|
||||
to use the :program:`sphinx-quickstart` tool here, though its use is by no means
|
||||
necessary.
|
||||
Sphinx is a *documentation generator* or a tool that translates a set of plain
|
||||
text source files into various output formats, automatically producing
|
||||
cross-references, indices, etc. That is, if you have a directory containing a
|
||||
bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown`
|
||||
documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),
|
||||
man pages and much more.
|
||||
|
||||
Sphinx focuses on documentation, in particular handwritten documentation,
|
||||
however, Sphinx can also be used to generate blogs, homepages and even books.
|
||||
Much of Sphinx's power comes from the richness of its default plain-text markup
|
||||
format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with
|
||||
it's :doc:`significant extensibility capabilities </development/index>`.
|
||||
|
||||
The goal of this document is to give you a quick taste of what Sphinx it is and
|
||||
how you might use it. When you're done here, you can check out the
|
||||
:doc:`installation guide </usage/installation>` followed by the intro to the
|
||||
default markup format used by Sphinx, :doc:`reStucturedText
|
||||
</usage/restructuredtext/index>`.
|
||||
|
||||
For a great "introduction" to writing docs in general -- the whys and hows, see
|
||||
also `Write the docs`__, written by Eric Holscher.
|
||||
|
||||
.. __: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
|
||||
|
||||
|
||||
Setting up the documentation sources
|
||||
------------------------------------
|
||||
|
||||
The root directory of a Sphinx collection of :term:`reStructuredText` document
|
||||
sources is called the :term:`source directory`. This directory also contains
|
||||
the Sphinx configuration file :file:`conf.py`, where you can configure all
|
||||
aspects of how Sphinx reads your sources and builds your documentation. [#]_
|
||||
The root directory of a Sphinx collection of plain-text document sources is
|
||||
called the :term:`source directory`. This directory also contains the Sphinx
|
||||
configuration file :file:`conf.py`, where you can configure all aspects of how
|
||||
Sphinx reads your sources and builds your documentation. [#]_
|
||||
|
||||
Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
|
||||
source directory and creates a default :file:`conf.py` with the most useful
|
||||
@ -26,9 +43,6 @@ configuration values from a few questions it asks you. To use this, run:
|
||||
|
||||
$ sphinx-quickstart
|
||||
|
||||
There is also an automatic "API documentation" generator called
|
||||
:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details.
|
||||
|
||||
|
||||
Defining document structure
|
||||
---------------------------
|
||||
|
Loading…
Reference in New Issue
Block a user