Improve the getting started docs
parent
6261427e66
commit
4adc1f5054
|
@ -0,0 +1,15 @@
|
||||||
|
Connecting Your Account
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
If you are going to import repositories from GitHub, Bitbucket, or GitLab,
|
||||||
|
you should connect your Read the Docs account to your repository host first.
|
||||||
|
Connecting your account allows for:
|
||||||
|
|
||||||
|
* Easier importing of your repositories
|
||||||
|
* Automatically configure your repository :doc:`webhooks`
|
||||||
|
* Log into Read the Docs with your GitHub, Bitbucket, or GitLab credentials
|
||||||
|
|
||||||
|
To connect your account, go to your *Settings* dashboard and select *Connected
|
||||||
|
Services*. From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
|
||||||
|
account. This process will ask you to authorize a connection to Read the Docs,
|
||||||
|
that allows us to read information about and clone your repositories.
|
|
@ -1,151 +0,0 @@
|
||||||
Getting Started
|
|
||||||
===============
|
|
||||||
|
|
||||||
This document will show you how to get up and running with Read the Docs.
|
|
||||||
You will have your docs imported on Read the Docs in 5 minutes,
|
|
||||||
displayed beautifully for the world.
|
|
||||||
|
|
||||||
If you are already using Sphinx or Markdown for your docs, skip ahead to
|
|
||||||
:ref:`getting_started:Import Your Docs`.
|
|
||||||
|
|
||||||
Write Your Docs
|
|
||||||
---------------
|
|
||||||
|
|
||||||
You have two options for formatting your documentation:
|
|
||||||
|
|
||||||
* `In reStructuredText`_
|
|
||||||
* `In Markdown`_
|
|
||||||
|
|
||||||
In reStructuredText
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
There is `a screencast`_ that will help you get started if you prefer.
|
|
||||||
|
|
||||||
Sphinx_ is a tool that makes it easy to create beautiful documentation.
|
|
||||||
Assuming you have Python_ already, `install Sphinx`_::
|
|
||||||
|
|
||||||
$ pip install sphinx sphinx-autobuild
|
|
||||||
|
|
||||||
Create a directory inside your project to hold your docs::
|
|
||||||
|
|
||||||
$ cd /path/to/project
|
|
||||||
$ mkdir docs
|
|
||||||
|
|
||||||
Run ``sphinx-quickstart`` in there::
|
|
||||||
|
|
||||||
$ cd docs
|
|
||||||
$ sphinx-quickstart
|
|
||||||
|
|
||||||
This quick start will walk you through creating the basic configuration; in most cases, you
|
|
||||||
can just accept the defaults. When it's done, you'll have an ``index.rst``, a
|
|
||||||
``conf.py`` and some other files. Add these to revision control.
|
|
||||||
|
|
||||||
Now, edit your ``index.rst`` and add some information about your project.
|
|
||||||
Include as much detail as you like (refer to the reStructuredText_ syntax
|
|
||||||
or `this template`_ if you need help). Build them to see how they look::
|
|
||||||
|
|
||||||
$ make html
|
|
||||||
|
|
||||||
.. note:: You can use ``sphinx-autobuild`` to auto-reload your docs. Run ``sphinx-autobuild . _build/html`` instead.
|
|
||||||
|
|
||||||
Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository.
|
|
||||||
Once you have Sphinx documentation in a public repository, you can start using Read the Docs.
|
|
||||||
|
|
||||||
In Markdown
|
|
||||||
~~~~~~~~~~~
|
|
||||||
|
|
||||||
You can use Markdown and reStructuredText in the same Sphinx project.
|
|
||||||
We support this natively on Read the Docs, and you can do it locally::
|
|
||||||
|
|
||||||
$ pip install recommonmark
|
|
||||||
|
|
||||||
Then in your ``conf.py``:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from recommonmark.parser import CommonMarkParser
|
|
||||||
|
|
||||||
source_parsers = {
|
|
||||||
'.md': CommonMarkParser,
|
|
||||||
}
|
|
||||||
|
|
||||||
source_suffix = ['.rst', '.md']
|
|
||||||
|
|
||||||
.. note:: Markdown doesn't support a lot of the features of Sphinx,
|
|
||||||
like inline markup and directives. However, it works for
|
|
||||||
basic prose content. reStructuredText is the preferred
|
|
||||||
format for technical documentation, please read `this blog post`_
|
|
||||||
for motivation.
|
|
||||||
|
|
||||||
.. _this blog post: http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
|
|
||||||
|
|
||||||
Sign Up and Connect an External Account
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
If you are going to import a repository from GitHub, Bitbucket or GitLab, you should
|
|
||||||
connect your account to your provider first. Connecting your account allows for
|
|
||||||
easier importing and enables Read the Docs to configure your repository webhooks
|
|
||||||
automatically.
|
|
||||||
|
|
||||||
To connect your account, go to your *Settings* dashboard and select *Connected
|
|
||||||
Services*. From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
|
|
||||||
account. This process will ask you to authorize a connection to Read the Docs,
|
|
||||||
that allows us to read information about and clone your repositories.
|
|
||||||
|
|
||||||
Import Your Docs
|
|
||||||
----------------
|
|
||||||
|
|
||||||
To import a repository, visit your dashboard_ and click Import_.
|
|
||||||
|
|
||||||
If you have a connected account, you will see a list of your repositories that
|
|
||||||
we are able to import. To import one of these projects, just click the import
|
|
||||||
icon next to the repository you'd like to import. This will bring up a form that
|
|
||||||
is already filled with your project's information. Feel free to edit any of
|
|
||||||
these properties, and the click **Next** to build your documentation.
|
|
||||||
|
|
||||||
Manually Import Your Docs
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
If you do not have a connected account, you will need select **Import Manually**
|
|
||||||
and enter the information for your repository yourself. You will also need to
|
|
||||||
manually configure the webhook for your repository as well. When importing your
|
|
||||||
project, you will be asked for the repository URL, along with some other
|
|
||||||
information for you new project. The URL is normally the URL or path name you'd
|
|
||||||
use to checkout, clone, or branch your repository. Some examples:
|
|
||||||
|
|
||||||
* Git: ``http://github.com/ericholscher/django-kong.git``
|
|
||||||
* Mercurial: ``https://bitbucket.org/ianb/pip``
|
|
||||||
* Subversion: ``http://varnish-cache.org/svn/trunk``
|
|
||||||
* Bazaar: ``lp:pasta``
|
|
||||||
|
|
||||||
Add an optional homepage URL and some tags, and then click **Next**.
|
|
||||||
|
|
||||||
Once your project is created, you'll need to manually configure the repository
|
|
||||||
webhook if you would like to have new changesets to trigger builds for your
|
|
||||||
project on Read the Docs. Go to your project's **Integrations** page to
|
|
||||||
configure a new webhook, or see :ref:`our steps for webhook creation <webhooks:Webhook Creation>`
|
|
||||||
for more information on this process.
|
|
||||||
|
|
||||||
Within a few seconds your code will automatically be fetched from your public repository,
|
|
||||||
and the documentation will be built.
|
|
||||||
Check out our :doc:`builds` page to learn more about how we build your docs,
|
|
||||||
and to troubleshoot any issues that arise.
|
|
||||||
|
|
||||||
Read the Docs will host multiple versions of your code. You can read more about
|
|
||||||
how to use this well on our :doc:`versions` page.
|
|
||||||
|
|
||||||
If you have any more trouble, don't hesitate to reach out to us. The :doc:`support` page has more information on getting in touch.
|
|
||||||
|
|
||||||
.. _a screencast: https://youtu.be/oJsUvBQyHBs
|
|
||||||
.. _Python: https://www.python.org/
|
|
||||||
.. _Sphinx: http://sphinx-doc.org/
|
|
||||||
.. _Markdown: http://daringfireball.net/projects/markdown/syntax
|
|
||||||
.. _Mkdocs: http://www.mkdocs.org/
|
|
||||||
.. _install Sphinx: http://sphinx-doc.org/latest/install.html
|
|
||||||
.. _install Mkdocs: http://www.mkdocs.org/#installation
|
|
||||||
.. _reStructuredText: http://sphinx-doc.org/rest.html
|
|
||||||
.. _this template: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#id1
|
|
||||||
.. _Sign up: https://readthedocs.org/accounts/signup
|
|
||||||
.. _log in: https://readthedocs.org/accounts/login
|
|
||||||
.. _dashboard: https://readthedocs.org/dashboard
|
|
||||||
.. _Import: https://readthedocs.org/dashboard/import
|
|
Binary file not shown.
After Width: | Height: | Size: 958 KiB |
113
docs/index.rst
113
docs/index.rst
|
@ -1,34 +1,53 @@
|
||||||
Welcome to Read The Docs
|
Read the Docs: Documentation Simplified
|
||||||
========================
|
=======================================
|
||||||
|
|
||||||
`Read the Docs`_ hosts documentation for the open source community.
|
`Read the Docs`_ simplifies software documentation
|
||||||
We support Sphinx_ docs written with reStructuredText_ and `CommonMark`_.
|
by automating building, versioning, and hosting of your docs for you.
|
||||||
We pull your code from your Subversion_, Bazaar_, Git_, and Mercurial_ repositories.
|
|
||||||
Then we build documentation and host it for you.
|
|
||||||
Think of it as *Continuous Documentation*.
|
Think of it as *Continuous Documentation*.
|
||||||
|
|
||||||
The code is open source, and `available on GitHub`_.
|
Never out of sync
|
||||||
|
Whenever you push code to your favorite version control system,
|
||||||
|
whether that is Git, Mercurial, Bazaar, or Subversion,
|
||||||
|
Read the Docs will automatically build your docs
|
||||||
|
so your code and documentation are always up-to-date.
|
||||||
|
|
||||||
|
Multiple versions
|
||||||
|
Read the Docs can host and build multiple versions of your docs
|
||||||
|
so having a 1.0 version of your docs and a 2.0 version
|
||||||
|
of your docs is as easy as having a separate branch or tag in your version control system.
|
||||||
|
|
||||||
|
Free and open source
|
||||||
|
Read the Docs is free and open source and hosts documentation
|
||||||
|
for nearly 100,000 large and small open source projects
|
||||||
|
in almost every human and computer language.
|
||||||
|
|
||||||
.. _Read the docs: http://readthedocs.org/
|
.. _Read the docs: http://readthedocs.org/
|
||||||
.. _Sphinx: http://sphinx.pocoo.org/
|
|
||||||
.. _reStructuredText: http://sphinx.pocoo.org/rest.html
|
|
||||||
.. _CommonMark: http://commonmark.org/
|
|
||||||
.. _Subversion: http://subversion.tigris.org/
|
|
||||||
.. _Bazaar: http://bazaar.canonical.com/
|
|
||||||
.. _Git: http://git-scm.com/
|
|
||||||
.. _Mercurial: https://www.mercurial-scm.org/
|
|
||||||
.. _available on GitHub: http://github.com/rtfd/readthedocs.org
|
|
||||||
|
|
||||||
The main documentation for the site is organized into a couple sections:
|
|
||||||
|
|
||||||
* :ref:`user-docs`
|
First steps
|
||||||
* :ref:`feature-docs`
|
-----------
|
||||||
* :ref:`about-docs`
|
|
||||||
|
|
||||||
Information about development is also available:
|
Are you new to software documentation
|
||||||
|
or are you looking to use your existing docs with Read the Docs?
|
||||||
|
Learn about documentation authoring tools such as Sphinx and MkDocs
|
||||||
|
to help you create fantastic documentation for your project.
|
||||||
|
|
||||||
|
* **Getting started**:
|
||||||
|
:doc:`With Sphinx <intro/getting-started-with-sphinx>` |
|
||||||
|
:doc:`With MkDocs <intro/getting-started-with-mkdocs>`
|
||||||
|
|
||||||
|
* **Importing your existing documentation**:
|
||||||
|
:doc:`Import guide <intro/import-guide>`
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
:hidden:
|
||||||
|
:caption: First Steps
|
||||||
|
|
||||||
|
intro/getting-started-with-sphinx
|
||||||
|
intro/getting-started-with-mkdocs
|
||||||
|
intro/import-guide
|
||||||
|
|
||||||
* :ref:`dev-docs`
|
|
||||||
* :ref:`design-docs`
|
|
||||||
|
|
||||||
.. _user-docs:
|
.. _user-docs:
|
||||||
|
|
||||||
|
@ -36,10 +55,10 @@ Information about development is also available:
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: User Documentation
|
:caption: User Documentation
|
||||||
|
|
||||||
getting_started
|
|
||||||
versions
|
versions
|
||||||
builds
|
builds
|
||||||
features
|
features
|
||||||
|
connected-accounts
|
||||||
support
|
support
|
||||||
faq
|
faq
|
||||||
yaml-config
|
yaml-config
|
||||||
|
@ -47,23 +66,6 @@ Information about development is also available:
|
||||||
api/index
|
api/index
|
||||||
embed
|
embed
|
||||||
|
|
||||||
.. _about-docs:
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
|
||||||
:caption: About Read the Docs
|
|
||||||
|
|
||||||
contribute
|
|
||||||
team
|
|
||||||
gsoc
|
|
||||||
code-of-conduct
|
|
||||||
privacy-policy
|
|
||||||
advertising/index
|
|
||||||
sponsors
|
|
||||||
open-source-philosophy
|
|
||||||
story
|
|
||||||
abandoned-projects
|
|
||||||
dmca/index
|
|
||||||
|
|
||||||
.. _feature-docs:
|
.. _feature-docs:
|
||||||
|
|
||||||
|
@ -86,11 +88,28 @@ Information about development is also available:
|
||||||
automatic-redirects
|
automatic-redirects
|
||||||
features/*
|
features/*
|
||||||
|
|
||||||
|
.. _about-docs:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
:caption: About Read the Docs
|
||||||
|
|
||||||
|
contribute
|
||||||
|
team
|
||||||
|
gsoc
|
||||||
|
code-of-conduct
|
||||||
|
privacy-policy
|
||||||
|
advertising/index
|
||||||
|
sponsors
|
||||||
|
open-source-philosophy
|
||||||
|
story
|
||||||
|
abandoned-projects
|
||||||
|
dmca/index
|
||||||
|
|
||||||
.. _dev-docs:
|
.. _dev-docs:
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 1
|
||||||
:caption: Developer Documentation
|
:caption: Developer Documentation
|
||||||
|
|
||||||
changelog
|
changelog
|
||||||
|
@ -105,6 +124,8 @@ Information about development is also available:
|
||||||
i18n
|
i18n
|
||||||
issue-labels
|
issue-labels
|
||||||
security
|
security
|
||||||
|
design
|
||||||
|
RTD Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>
|
||||||
|
|
||||||
.. _business-docs:
|
.. _business-docs:
|
||||||
|
|
||||||
|
@ -121,13 +142,3 @@ Information about development is also available:
|
||||||
:caption: Custom Install Documentation
|
:caption: Custom Install Documentation
|
||||||
|
|
||||||
custom_installs/index
|
custom_installs/index
|
||||||
|
|
||||||
.. _design-docs:
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
|
||||||
:caption: Designer Documentation
|
|
||||||
|
|
||||||
design
|
|
||||||
Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>
|
|
||||||
|
|
||||||
|
|
|
@ -151,4 +151,4 @@ Importing your docs
|
||||||
One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility!
|
One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility!
|
||||||
Simply provide us with the clone URL to your repo, we'll pull your code, extract your docs, and build them!
|
Simply provide us with the clone URL to your repo, we'll pull your code, extract your docs, and build them!
|
||||||
We make available a post-commit webhook that can be configured to update the docs whenever you commit to your repo.
|
We make available a post-commit webhook that can be configured to update the docs whenever you commit to your repo.
|
||||||
See our :doc:`getting_started` page to learn more.
|
See :doc:`/intro/import-guide` to learn more.
|
||||||
|
|
|
@ -0,0 +1,66 @@
|
||||||
|
Getting Started with MkDocs
|
||||||
|
===========================
|
||||||
|
|
||||||
|
MkDocs is a documentation generator that focuses on speed and simplicity.
|
||||||
|
It has many great features including:
|
||||||
|
|
||||||
|
* Preview your documentation as you write it
|
||||||
|
* Easy customization with themes and extensions
|
||||||
|
* Writing documentation with Markdown
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
MkDocs is a great choice for building technical documentation.
|
||||||
|
However, Read the Docs also supports :doc:`Sphinx </intro/getting-started-with-sphinx>`,
|
||||||
|
another tool for writing and building documentation.
|
||||||
|
|
||||||
|
|
||||||
|
Quick start
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Assuming you have Python already, `install MkDocs`_:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ pip install mkdocs
|
||||||
|
|
||||||
|
Setup your MkDocs project:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ mkdocs new .
|
||||||
|
|
||||||
|
This command creates ``mkdocs.yml`` which holds your MkDocs configuration,
|
||||||
|
and ``docs/index.md`` which is the Markdown file
|
||||||
|
that is the entry point for your documentation.
|
||||||
|
|
||||||
|
You can edit this ``index.md`` file to add more details about your project
|
||||||
|
and then you can build your documentation:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ mkdocs serve
|
||||||
|
|
||||||
|
This command builds your Markdown files into HTML
|
||||||
|
and starts a development server to browse your documentation.
|
||||||
|
Open up http://127.0.0.1:8000/ in your web browser to see your documentation.
|
||||||
|
You can make changes to your Markdown files and your docs will automatically rebuild.
|
||||||
|
|
||||||
|
Once you have your documentation in a public repository such GitHub, Bitbucket, or GitLab,
|
||||||
|
you can start using Read the Docs by :doc:`importing your docs </intro/import-guide>`.
|
||||||
|
|
||||||
|
.. _install MkDocs: https://www.mkdocs.org/#installation
|
||||||
|
|
||||||
|
|
||||||
|
External resources
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Here are some external resources to help you learn more about MkDocs.
|
||||||
|
|
||||||
|
* `MkDocs documentation`_
|
||||||
|
* `Markdown syntax guide`_
|
||||||
|
* `Writing your docs with MkDocs`_
|
||||||
|
|
||||||
|
.. _MkDocs documentation: https://www.mkdocs.org/
|
||||||
|
.. _Markdown syntax guide: http://daringfireball.net/projects/markdown/syntax
|
||||||
|
.. _Writing your docs with MkDocs: https://www.mkdocs.org/user-guide/writing-your-docs/
|
|
@ -0,0 +1,128 @@
|
||||||
|
Getting Started with Sphinx
|
||||||
|
===========================
|
||||||
|
|
||||||
|
Sphinx is a powerful documentation generator that
|
||||||
|
has many great features for writing technical documentation including:
|
||||||
|
|
||||||
|
* Generate web pages, printable PDFs, documents for e-readers (ePub),
|
||||||
|
and more all from the same sources
|
||||||
|
* You can use reStructuredText or :ref:`Markdown <intro/getting-started-with-sphinx:Using Markdown with Sphinx>`
|
||||||
|
to write documentation
|
||||||
|
* An extensive system of cross-referencing code and documentation
|
||||||
|
* Syntax highlighted code samples
|
||||||
|
* A vibrant ecosystem of first and third-party extensions_
|
||||||
|
|
||||||
|
.. _extensions: http://www.sphinx-doc.org/en/master/ext/builtins.html#builtin-sphinx-extensions
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Sphinx is a great choice for building technical documentation
|
||||||
|
and many projects large and small use Sphinx
|
||||||
|
including the Django project and the Python programming language.
|
||||||
|
However, Read the Docs also supports :doc:`MkDocs </intro/getting-started-with-mkdocs>`,
|
||||||
|
another tool for writing and building documentation.
|
||||||
|
|
||||||
|
|
||||||
|
Quick start video
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
This screencast will help you get started or you can
|
||||||
|
:ref:`read our guide below <intro/getting-started-with-sphinx:Quick start>`.
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
|
||||||
|
<div style="text-align: center; margin-bottom: 2em;">
|
||||||
|
<iframe width="100%" height="350" src="https://www.youtube.com/embed/oJsUvBQyHBs?rel=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
|
||||||
|
Quick start
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Assuming you have Python already, `install Sphinx`_:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ pip install sphinx
|
||||||
|
|
||||||
|
Create a directory inside your project to hold your docs:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ cd /path/to/project
|
||||||
|
$ mkdir docs
|
||||||
|
|
||||||
|
Run ``sphinx-quickstart`` in there:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ cd docs
|
||||||
|
$ sphinx-quickstart
|
||||||
|
|
||||||
|
This quick start will walk you through creating the basic configuration; in most cases, you
|
||||||
|
can just accept the defaults. When it's done, you'll have an ``index.rst``, a
|
||||||
|
``conf.py`` and some other files. Add these to revision control.
|
||||||
|
|
||||||
|
Now, edit your ``index.rst`` and add some information about your project.
|
||||||
|
Include as much detail as you like (refer to the reStructuredText_ syntax
|
||||||
|
or `this template`_ if you need help). Build them to see how they look:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ make html
|
||||||
|
|
||||||
|
Your ``index.rst`` has been built into ``index.html``
|
||||||
|
in your documentation output directory (typically ``_build/html/index.html``).
|
||||||
|
Open this file in your web browser to see your docs.
|
||||||
|
|
||||||
|
Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository.
|
||||||
|
Once you have Sphinx documentation in a public repository, you can start using Read the Docs
|
||||||
|
by :doc:`importing your docs </intro/import-guide>`.
|
||||||
|
|
||||||
|
.. _install Sphinx: http://sphinx-doc.org/latest/install.html
|
||||||
|
.. _reStructuredText: http://sphinx-doc.org/rest.html
|
||||||
|
.. _this template: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#id1
|
||||||
|
|
||||||
|
Using Markdown with Sphinx
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
You can use Markdown and reStructuredText in the same Sphinx project.
|
||||||
|
We support this natively on Read the Docs, and you can do it locally:
|
||||||
|
|
||||||
|
.. sourcecode:: bash
|
||||||
|
|
||||||
|
$ pip install recommonmark
|
||||||
|
|
||||||
|
Then in your ``conf.py``:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
from recommonmark.parser import CommonMarkParser
|
||||||
|
|
||||||
|
source_parsers = {
|
||||||
|
'.md': CommonMarkParser,
|
||||||
|
}
|
||||||
|
|
||||||
|
source_suffix = ['.rst', '.md']
|
||||||
|
|
||||||
|
.. warning:: Markdown doesn't support a lot of the features of Sphinx,
|
||||||
|
like inline markup and directives. However, it works for
|
||||||
|
basic prose content. reStructuredText is the preferred
|
||||||
|
format for technical documentation, please read `this blog post`_
|
||||||
|
for motivation.
|
||||||
|
|
||||||
|
.. _this blog post: http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
|
||||||
|
|
||||||
|
|
||||||
|
External resources
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Here are some external resources to help you learn more about Sphinx.
|
||||||
|
|
||||||
|
* `Sphinx documentation`_
|
||||||
|
* `RestructuredText primer`_
|
||||||
|
* `An introduction to Sphinx and Read the Docs for technical writers`_
|
||||||
|
|
||||||
|
.. _Sphinx documentation: http://www.sphinx-doc.org/
|
||||||
|
.. _RestructuredText primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
|
||||||
|
.. _An introduction to Sphinx and Read the Docs for technical writers: http://ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/
|
|
@ -0,0 +1,62 @@
|
||||||
|
Importing Your Documentation
|
||||||
|
============================
|
||||||
|
|
||||||
|
To import a documentation repository, visit your `Read the Docs dashboard`_ and click Import_.
|
||||||
|
|
||||||
|
If you have :doc:`connected your Read the Docs account <../connected-accounts>` to GitHub, Bitbucket, or GitLab,
|
||||||
|
you will see a list of your repositories that we are able to import.
|
||||||
|
To import one of these projects, just click the import
|
||||||
|
icon next to the repository you'd like to import. This will bring up a form that
|
||||||
|
is already filled with your project's information. Feel free to edit any of
|
||||||
|
these properties, and the click **Next** to
|
||||||
|
:ref:`build your documentation <intro/import-guide:Building your documentation>`.
|
||||||
|
|
||||||
|
.. _Read the Docs dashboard: https://readthedocs.org/dashboard
|
||||||
|
.. _Import: https://readthedocs.org/dashboard/import
|
||||||
|
|
||||||
|
|
||||||
|
.. figure:: /img/first-steps/import-a-repository.png
|
||||||
|
:align: right
|
||||||
|
:figwidth: 300px
|
||||||
|
|
||||||
|
Importing a repository
|
||||||
|
|
||||||
|
|
||||||
|
Manually import your docs
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
If you do not have a connected account, you will need select **Import Manually**
|
||||||
|
and enter the information for your repository yourself. You will also need to
|
||||||
|
manually configure the webhook for your repository as well. When importing your
|
||||||
|
project, you will be asked for the repository URL, along with some other
|
||||||
|
information for you new project. The URL is normally the URL or path name you'd
|
||||||
|
use to checkout, clone, or branch your repository. Some examples:
|
||||||
|
|
||||||
|
* Git: ``https://github.com/ericholscher/django-kong.git``
|
||||||
|
* Mercurial: ``https://bitbucket.org/ianb/pip``
|
||||||
|
* Subversion: ``http://varnish-cache.org/svn/trunk``
|
||||||
|
* Bazaar: ``lp:pasta``
|
||||||
|
|
||||||
|
Add an optional homepage URL and some tags, and then click **Next**.
|
||||||
|
|
||||||
|
Once your project is created, you'll need to manually configure the repository
|
||||||
|
webhook if you would like to have new changes trigger builds for your
|
||||||
|
project on Read the Docs. Go to your project's **Integrations** page to
|
||||||
|
configure a new webhook, or see :ref:`our steps for webhook creation <webhooks:Webhook Creation>`
|
||||||
|
for more information on this process.
|
||||||
|
|
||||||
|
|
||||||
|
Building your documentation
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Within a few seconds of completing the import process,
|
||||||
|
your code will automatically be fetched from your public repository,
|
||||||
|
and the documentation will be built.
|
||||||
|
Check out our :doc:`/builds` page to learn more about how Read the Docs builds your docs,
|
||||||
|
and to troubleshoot any issues that arise.
|
||||||
|
|
||||||
|
Read the Docs will host multiple versions of your code. You can read more about
|
||||||
|
how to use this well on our :doc:`/versions` page.
|
||||||
|
|
||||||
|
If you have any more trouble, don't hesitate to reach out to us.
|
||||||
|
The :doc:`/support` page has more information on getting in touch.
|
|
@ -23,7 +23,7 @@ repository provider such as GitHub, GitLab, or Bitbucket.
|
||||||
Webhook Creation
|
Webhook Creation
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
If you import a project using a :ref:`connected account <getting_started:Sign Up and Connect an External Account>`,
|
If you have :doc:`connected your Read the Docs account </connected-accounts>` to GitHub, Bitbucket, or GitLab,
|
||||||
a webhook will be set up automatically for your repository. However, if your
|
a webhook will be set up automatically for your repository. However, if your
|
||||||
project was not imported through a connected account, you may need to
|
project was not imported through a connected account, you may need to
|
||||||
manually configure a webhook for your project.
|
manually configure a webhook for your project.
|
||||||
|
|
Loading…
Reference in New Issue