Documenting Sagrada, the Platform

[Tarek Ziade]

Hey

We have http://docs.services.mozilla.com, and for each service we have a
dedicated section to display the APIs.

Now that we're building platform libraries/tools, I see that everyone's
happily working with readthedocs.org and started a Sphinx by project

- Queuey : http://queuey.readthedocs.org
- Circus : http://circus.readthedocs.org
- Powerhose: http://powerhose.readthedocs.org
- Metlog-Py : http://metlog-py.readthedocs.org

(did I miss one ?)

But that frustrates me to have yet other places to look for our doc.

Proposal:

I propose that we add a 'sagrada' root page in our central doc at
http://docs.services.mozilla.com/sagrada/, and create a small sphinx
extension which would simply pull from a list of Git repos the
standalone Sphinx doc we have in projects,
and make it a subdirectory in http://docs.services.mozilla.com/sagrada.

Btw, As soon as this issue is fixed by IT: (Your subversion account has
been disabled due to inactivity.) I will reactivate the hook that updates
automatically our website.

Cheers
Tarek
_______________________________________________
Services-dev mailing list
Servic...@mozilla.org
https://mail.mozilla.org/listinfo/services-dev

[Hanno Schlichting]

On 29.03.2012, at 14:37 , Tarek Ziade wrote:
> Now that we're building platform libraries/tools, I see that everyone's happily working with readthedocs.org and started a Sphinx by project
>
> - Queuey : http://queuey.readthedocs.org
> - Circus : http://circus.readthedocs.org
> - Powerhose: http://powerhose.readthedocs.org
> - Metlog-Py : http://metlog-py.readthedocs.org
>
> (did I miss one ?)

There's two more we have in the Queuey ecosystem:

http://qdo.readthedocs.org
http://zktools.readthedocs.org

> I propose that we add a 'sagrada' root page in our central doc at http://docs.services.mozilla.com/sagrada/, and create a small sphinx
> extension which would simply pull from a list of Git repos the standalone Sphinx doc we have in projects,
> and make it a subdirectory in http://docs.services.mozilla.com/sagrada.

Sounds good in principle.

How does that work with the Sphinx autodoc extension and its need to be able to import the code?

Hanno

[Tarek Ziade]

On 3/29/12 3:35 PM, Hanno Schlichting wrote:
> On 29.03.2012, at 14:37 , Tarek Ziade wrote:
>> Now that we're building platform libraries/tools, I see that everyone's happily working with readthedocs.org and started a Sphinx by project
>>
>> - Queuey : http://queuey.readthedocs.org
>> - Circus : http://circus.readthedocs.org
>> - Powerhose: http://powerhose.readthedocs.org
>> - Metlog-Py : http://metlog-py.readthedocs.org
>>
>> (did I miss one ?)
> There's two more we have in the Queuey ecosystem:
>
> http://qdo.readthedocs.org
> http://zktools.readthedocs.org
>
>> I propose that we add a 'sagrada' root page in our central doc at http://docs.services.mozilla.com/sagrada/, and create a small sphinx
>> extension which would simply pull from a list of Git repos the standalone Sphinx doc we have in projects,
>> and make it a subdirectory in http://docs.services.mozilla.com/sagrada.
> Sounds good in principle.
>
> How does that work with the Sphinx autodoc extension and its need to be able to import the code?

pointing a pip requirements file like readthedocs does, and also adding
the project's root in the path ?

[Alexis Métaireau]

We also have cornice (http://packages.python.org/cornice)

Also, because "sagrada" is a name we use for both the libs and the
services we are providing, maybe we should go for something a little
bit less unusual? what do you think about "libraries", for instance?

Alex

[Toby Elliott]

The basic idea is sound. There should be a technical page documenting Sagrada and tying all these pieces together. I'm still wresting with some of what should be on there.

It can't replace the Sagrada wiki page, though. I don't think we want to bleed stuff like quarterly goals and other internal notes onto pages that are focused on development, howtos and technical specifications.

Toby

[Tarek Ziade]

On 3/30/12 12:12 AM, Toby Elliott wrote:
> The basic idea is sound. There should be a technical page documenting Sagrada and tying all these pieces together. I'm still wresting with some of what should be on there.
>
> It can't replace the Sagrada wiki page, though. I don't think we want to bleed stuff like quarterly goals and other internal notes onto pages that are focused on development, howtos and technical specifications.

Yeah definitely -- that does not replace the wiki with Q goals.

For me, the target audience is developers and potential contributors,
users of our libraries/isolated services like queuey etc.

I really like what everyone has built on their side in standalone Sphinx
instances -- that's exactly the doc I want as a developer.

if we can combine those Sphinx in a single 'book' somehow, that would
make me happy, and that'd be the media I'd point to people, saying:

"hey, we're building a platform, look at all those cool tools and
services". And that'd be completely orthogonal to the prep work we do
in goals, spec work etc.

Cheers

[Tarek Ziade]

On 3/29/12 2:37 PM, Tarek Ziade wrote:
> Btw, As soon as this issue is fixed by IT: (Your subversion account
> has been disabled due to inactivity.) I will reactivate the hook that
> updates
> automatically our website.
>

This is done. There's a hook now on github, and the subversion repo get
refreshed w/ a new Sphinx build on every commit.

Ryan: Not sure if it's intended but
http://docs.services.mozilla.com/aitc/ is not listed in the main index

[Gregory Szorc]

On 3/29/12 3:33 PM, Tarek Ziade wrote:
> I really like what everyone has built on their side in standalone
> Sphinx instances -- that's exactly the doc I want as a developer.
>
> if we can combine those Sphinx in a single 'book' somehow, that would
> make me happy, and that'd be the media I'd point to people, saying:
>
> "hey, we're building a platform, look at all those cool tools and
> services". And that'd be completely orthogonal to the prep work we do
> in goals, spec work etc.

This is a hard problem.

Keeping API docs in sync with a single sphinx instance will be
challenging: as that single Sphinx instance would need a copy of all
source code. Doable, but a lot of work (Git's behavior of pinning
submodules to a specific commit doesn't help matters for the case where
we want to always render the latest/greatest revision of the docs).

How about a master "docs" repository (like we have now) that contains
all the reference material like specifications. This could be
supplemented with per-project Sphinx repositories also living on the
same domain. With a little template magic, we could make it look like
the same site. In short, we essentially replicate the behavior of
readthedocs on docs.services and add relative links in the main site.

[Richard Newman]

> Keeping API docs in sync with a single sphinx instance will be challenging: as that single Sphinx instance would need a copy of all source code. Doable, but a lot of work (Git's behavior of pinning submodules to a specific commit doesn't help matters for the case where we want to always render the latest/greatest revision of the docs).

If this is the only obstacle, might I suggest subgit?

http://rustyklophaus.com/articles/20100124-SubmodulesAndSubreposDoneRight.html

I use/used this successfully for android-sync.