EbookFoundation
/
readthedocs.org
mirror of https://github.com/EbookFoundation/readthedocs.org.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve the getting started docs

humitos/integrations/handle-error-codes
David Fischer 2018-09-28 15:42:50 -07:00
parent 6261427e66
commit 4adc1f5054
No known key found for this signature in database
GPG Key ID: F0C9B0ADA737AB60
9 changed files with 335 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/connected-accounts.rst Normal file
View File

@ -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.

151
docs/getting_started.rst
View File

@ -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

BIN
docs/img/first-steps/import-a-repository.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 958 KiB

113
docs/index.rst
View File

@ -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/>

2
docs/install.rst
View File

@ -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.

66
docs/intro/getting-started-with-mkdocs.rst Normal file
View File

@ -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/

128
docs/intro/getting-started-with-sphinx.rst Normal file
View File

@ -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/

62
docs/intro/import-guide.rst Normal file
View File

@ -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.

2
docs/webhooks.rst
View File

@ -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.