diff --git a/docs/_static/images/first-steps/import-a-repository.png b/docs/_static/images/first-steps/import-a-repository.png new file mode 100644 index 00000000000..252f69834df Binary files /dev/null and b/docs/_static/images/first-steps/import-a-repository.png differ diff --git a/docs/_static/images/first-steps/mkdocs-hello-world.png b/docs/_static/images/first-steps/mkdocs-hello-world.png new file mode 100644 index 00000000000..0c1bde0bf17 Binary files /dev/null and b/docs/_static/images/first-steps/mkdocs-hello-world.png differ diff --git a/docs/_static/images/first-steps/sphinx-hello-world.png b/docs/_static/images/first-steps/sphinx-hello-world.png new file mode 100644 index 00000000000..cc7639664cf Binary files /dev/null and b/docs/_static/images/first-steps/sphinx-hello-world.png differ diff --git a/docs/conf.py b/docs/conf.py index 71d66d0a881..1cb99137f38 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -71,7 +71,7 @@ gettext_compact = False html_theme = 'sphinx_rtd_theme' -# html_static_path = ['_static'] +html_static_path = ['_static'] html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] html_logo = 'img/logo.svg' html_theme_options = { diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst new file mode 100644 index 00000000000..3db7ed6ca51 --- /dev/null +++ b/docs/connected-accounts.rst @@ -0,0 +1,20 @@ +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` + which allow Read the Docs to build your docs on every change to your repository +* Log into Read the Docs with your GitHub, Bitbucket, or GitLab credentials + +If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab +credentials, you're all done. Your account is connected. + +To connect your unconnected 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. diff --git a/docs/getting_started.rst b/docs/getting_started.rst deleted file mode 100644 index 3eb2330a9bd..00000000000 --- a/docs/getting_started.rst +++ /dev/null @@ -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 ` -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 diff --git a/docs/index.rst b/docs/index.rst index 4258087a11a..536ac4c516d 100644 --- a/docs/index.rst +++ b/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. -We support Sphinx_ docs written with reStructuredText_ and `CommonMark`_. -We pull your code from your Subversion_, Bazaar_, Git_, and Mercurial_ repositories. -Then we build documentation and host it for you. +`Read the Docs`_ simplifies software documentation +by automating building, versioning, and hosting of your docs for you. 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/ -.. _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` -* :ref:`feature-docs` -* :ref:`about-docs` +First steps +----------- + +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 ` | + :doc:`With MkDocs ` + +* **Importing your existing documentation**: + :doc:`Import guide ` + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: First Steps -Information about development is also available: + intro/getting-started-with-sphinx + intro/getting-started-with-mkdocs + intro/import-guide -* :ref:`dev-docs` -* :ref:`design-docs` .. _user-docs: @@ -36,10 +55,10 @@ Information about development is also available: :maxdepth: 2 :caption: User Documentation - getting_started versions builds features + connected-accounts support faq yaml-config @@ -47,25 +66,6 @@ Information about development is also available: api/index embed -.. _about-docs: - -.. toctree:: - :maxdepth: 2 - :caption: About Read the Docs - - contribute - roadmap - team - gsoc - code-of-conduct - privacy-policy - advertising/index - sponsors - open-source-philosophy - story - abandoned-projects - dmca/index - .. _feature-docs: .. toctree:: @@ -87,11 +87,29 @@ Information about development is also available: automatic-redirects features/* +.. _about-docs: + +.. toctree:: + :maxdepth: 1 + :caption: About Read the Docs + + contribute + roadmap + team + gsoc + code-of-conduct + privacy-policy + advertising/index + sponsors + open-source-philosophy + story + abandoned-projects + dmca/index .. _dev-docs: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Developer Documentation changelog @@ -107,6 +125,8 @@ Information about development is also available: i18n issue-labels security + design + RTD Theme .. _business-docs: @@ -123,13 +143,3 @@ Information about development is also available: :caption: Custom Install Documentation custom_installs/index - -.. _design-docs: - -.. toctree:: - :maxdepth: 2 - :caption: Designer Documentation - - design - Theme - diff --git a/docs/install.rst b/docs/install.rst index 68c335882db..5aa2cbd1125 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -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! 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. -See our :doc:`getting_started` page to learn more. +See :doc:`/intro/import-guide` to learn more. diff --git a/docs/intro/getting-started-with-mkdocs.rst b/docs/intro/getting-started-with-mkdocs.rst new file mode 100644 index 00000000000..04b09f945f7 --- /dev/null +++ b/docs/intro/getting-started-with-mkdocs.rst @@ -0,0 +1,73 @@ +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 `, + 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. + +.. figure:: ../_static/images/first-steps/mkdocs-hello-world.png + :align: right + :figwidth: 300px + :target: ../_static/images/first-steps/mkdocs-hello-world.png + + Your MkDocs project is built + +Once you have your documentation in a public repository such as GitHub, Bitbucket, or GitLab, +you can start using Read the Docs by :doc:`importing your docs `. + +.. _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/ diff --git a/docs/intro/getting-started-with-sphinx.rst b/docs/intro/getting-started-with-sphinx.rst new file mode 100644 index 00000000000..782cdd39b8a --- /dev/null +++ b/docs/intro/getting-started-with-sphinx.rst @@ -0,0 +1,127 @@ +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 ` + 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 + + +Quick start video +----------------- + +This screencast will help you get started or you can +:ref:`read our guide below `. + +.. raw:: html + +
+ +
+ + +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. + +.. figure:: ../_static/images/first-steps/sphinx-hello-world.png + :align: right + :figwidth: 300px + :target: ../_static/images/first-steps/sphinx-hello-world.png + + Your Sphinx project is built + +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 `. + +.. _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/ diff --git a/docs/intro/import-guide.rst b/docs/intro/import-guide.rst new file mode 100644 index 00000000000..b44cdfe4d67 --- /dev/null +++ b/docs/intro/import-guide.rst @@ -0,0 +1,68 @@ +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 `. + +.. _Read the Docs dashboard: https://readthedocs.org/dashboard +.. _Import: https://readthedocs.org/dashboard/import + + +.. figure:: ../_static/images/first-steps/import-a-repository.png + :align: right + :figwidth: 300px + :target: ../_static/images/first-steps/import-a-repository.png + + 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 ` +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. + +Some documentation projects require additional configuration to build +such as specifying a certain version of Python or installing additional dependencies. +You can configure these settings in a ``readthedocs.yml`` file. +See our :doc:`/yaml-config` docs for more details. + +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. diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 47b2e0e4aee..ecf18611b50 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -23,7 +23,7 @@ repository provider such as GitHub, GitLab, or Bitbucket. Webhook Creation ---------------- -If you import a project using a :ref:`connected account `, +If you have :doc:`connected your Read the Docs account ` to GitHub, Bitbucket, or GitLab, 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 manually configure a webhook for your project.