Merge pull request #2801 from rtfd/subproject-docs

Add some docs on subprojects

Author: ericholscher

docs/subprojects.rst

@@ -1,18 +1,43 @@
 Subprojects
 ===========
 
-We support the concept of Subprojects.
-If you add a subproject to a project,
-that documentation will also be served under the parent project's subdomain.
+Projects can be configured in a nested manner, by configuring a project as a
+*subproject* of another project. This allows for documentation projects to share
+a search index and a namespace or custom domain, but still be maintained
+independently.
 
-For example,
-Kombu is a subproject of celery,
-so you can access it on the `celery.readthedocs.io` domain:
+For example, a parent project, ``Foo`` is set up with a subproject, ``Bar``. The
+documentation for ``Foo`` will be available at:
 
-http://celery.readthedocs.io/projects/kombu/en/latest/
+https://foo.readthedocs.io/en/latest/
 
-This also works the same for CNAMEs:
+The documentation for ``Bar`` will be available under this same path:
 
-http://docs.celeryproject.org/projects/kombu/en/latest/
+https://foo.readthedocs.io/projects/bar/en/latest/
 
-You can add subprojects in the Admin section for your project.
+Adding a Subproject
+-------------------
+
+In the admin dashboard for your project, select "Subprojects" from the menu.
+From this page you can add a subproject by typing in the project slug.
+
+Sharing a Custom Domain
+-----------------------
+
+Projects and subprojects can also be used to share a custom domain with a number
+of projects. To configure this, one project should be established as the parent
+project. This project will be configured with a custom domain. Projects can then
+be added as subprojects to this parent project.
+
+If the example project ``Foo`` was set up with a custom domain,
+``docs.example.com``, the URLs for projects ``Foo`` and ``Bar`` would
+respectively be at: http://docs.example.com/en/latest/ and
+http://docs.example.com/projects/bar/en/latest/
+
+Search
+------
+
+Projects that are configured as subprojects will share a search index with their
+parent and sibling projects. This is currently the only way to share search
+indexes between projects, we do not yet support sharing search indexes between
+arbitrary projects.