Add some docs on subprojects #2801
Conversation
Clarify usage around subprojects, how they can be used, and other features.
agjohnson
added
PR: work in progress
There was a problem hiding this comment.
Should confirm that this doesn't conflict with #2786, but looks good.
|
|
||
| http://docs.celeryproject.org/projects/kombu/en/latest/ | ||
| https://foo.readthedocs.io/projects/bar/en/latest/ |
There was a problem hiding this comment.
These should be real projects, I think. Either ones we control, of the ones from #2786
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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" :)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
docs/subprojects.rst
Outdated
|
|
||
| In the admin dashboard for your project, select "Subprojects" from the menu. | ||
| From this page you can add a subproject by typing in the id of the project. |
There was a problem hiding this comment.
The id of the project? I thought it was the slug -- we should also clarify it's only projects you own.
There was a problem hiding this comment.
Ah yes, correct.
I don't think this is limited to projects you own currently. We'll need this doc update along with the form change on this -- can address that separately when it comes time to work on that.
There was a problem hiding this comment.
Also, on slug vs id -- slug is a development concept that likely means nothing to some users. Eventually, we should settle on language around this -- or hopefully just phase out anything that requires you to know the project slug.
docs/subprojects.rst
Outdated
| Projects that are configured as subprojects will share a search index with their | ||
| parent and sibling projects. This is the only way to share search indexes, they | ||
| are not shared between arbitrary projects. |
There was a problem hiding this comment.
This last sentence feels weird. Why are we clarifying they are not shared between arbitrary projects? Also, I feel like we'll probably want to build a way to create custom search indexes (eg. Collections) so it feels weird to be so firm with the negative here.
There was a problem hiding this comment.
This was a question i've had, so I included it. Collections would be a more correct answer, but nothing we have an answer for now.
There was a problem hiding this comment.
I made this less firm with bd4f6e9
| 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 |
There was a problem hiding this comment.
I think those two commas are not needed. I would write:
For example, a parent project
Foois set up with a subprojectBar. The
|
|
||
| http://docs.celeryproject.org/projects/kombu/en/latest/ | ||
| https://foo.readthedocs.io/projects/bar/en/latest/ |
There was a problem hiding this comment.
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" :)
agjohnson
added
PR: work in progress
|
Gonna merge these, so we actually have some subproject docs. Can be updated/improved later. |
Clarify usage around subprojects, how they can be used, and other features.