Merge pull request #4676 from rtfd/davidfischer/docs-getting-started-…

…improvements Improve the getting started docs
readthedocs · Oct 5, 2018 · d3d922d · d3d922d
2 parents 35695d1 + 66ea0f3
commit d3d922d
Show file tree

Hide file tree

Showing 12 changed files with 354 additions and 207 deletions.
diff --git a/docs/_static/images/first-steps/import-a-repository.png b/docs/_static/images/first-steps/import-a-repository.png
diff --git a/docs/_static/images/first-steps/mkdocs-hello-world.png b/docs/_static/images/first-steps/mkdocs-hello-world.png
diff --git a/docs/_static/images/first-steps/sphinx-hello-world.png b/docs/_static/images/first-steps/sphinx-hello-world.png
diff --git 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
@@ -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 <https://readthedocs.org/accounts/social/connections/>`_.
+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
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,71 +1,71 @@
-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 <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
 
-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:
 
 .. toctree::
    :maxdepth: 2
    :caption: User Documentation
 
-   getting_started
    versions
    builds
    features
+   connected-accounts
    support
    faq
    yaml-config
    guides/index
    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
@@ -106,6 +124,8 @@ Information about development is also available:
    i18n
    issue-labels
    security
+   design
+   RTD Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>
 
 .. _business-docs:
 
@@ -122,13 +142,3 @@ Information about development is also available:
    :caption: Custom Install Documentation
 
    custom_installs/index
-
-.. _design-docs:
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Designer Documentation
-
-   design
-   Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>
-
diff --git 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.