Skip to content

Add some docs on subprojects #2801

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 31, 2017
Merged

Add some docs on subprojects #2801

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea8d2f2
Add some docs on subprojects
agjohnson Apr 18, 2017
bd4f6e9
Clarify project slug, pull back on language on subproject search
agjohnson Apr 18, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 35 additions & 10 deletions docs/subprojects.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think those two commas are not needed. I would write:

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/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These should be real projects, I think. Either ones we control, of the ones from #2786

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put bunk data here specifically to avoid doc rot like the celery example. #2786 adds some examples that don't seem well established or static -- I'm not seeing many links between the parent and child projects. If there were stronger examples of subprojects, I'd be +1 on real links.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of using generic projects (foo and bar) in the general idea of the explanation. Maybe we can have another section with real life examples that point to projects and sub-projects so the user can see how they really work. If we don't control them, we can add a note like: "it may fails -said Tusam" :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, I guess my real issue is that it's linked, so people will try to click on it and get a 404. We should just make sure it isn't linked in a real fashion. +1 on having both fake & real examples tho.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The celery example isn't 'doc rot' per se (latest update was December?), but more that they never had the subproject and the parent project integrated together because it takes a concentrated amount of effort to get such integration working.

I'm definitely in favor of having working examples available.


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.