Plone

›

Documentation Team

Sphinx for Plone doc ?

14 Messages

Tarek Ziadé

Reply Threaded

Hello All,

I haven't seen anyone talk about that yet, so...

Sphinx rocks. It is used for Python (http://docs.python.org/dev) and many framework out there move to it.

Since its is reStructuredText based it is amazingly simple to start a documentation project on an existing code base. It is also a very gentle and nice way to push developers to write documentation: their doctests are already available and other text files probably just need to be reviewed a bit.

Rebuilding an up-to-date documentation is also dead easy: add a svn post-commit hook that call Sphinx make script and you're done.

I think I would be a big win for Plone to have a Sphinx-based documentation site that would complete
apis.plone.org for instance. (If I was not involved in other projects at this time I would probably go ahead and start something up on the top of plone code to demonstrate it. ;-) )

Any opinions about that ?

Tarek

Martin Aspeli-2

Re: Sphinx for Plone doc ?

Reply Threaded

Tarek Ziadé wrote:

> Hello All,
>
> I haven't seen anyone talk about that yet, so...
>
> Sphinx rocks. It is used for Python (http://docs.python.org/dev) and many
> framework out there move to it.
>
> Since its is reStructuredText based it is amazingly simple to start a
> documentation project on an existing code base. It is also a very gentle and
> nice way to push developers to write documentation: their doctests are
> already available and other text files probably just need to be reviewed a
> bit.
>
> Rebuilding an up-to-date documentation is also dead easy: add a svn
> post-commit hook that call Sphinx make script and you're done.
>
> I think I would be a big win for Plone to have a Sphinx-based documentation
> site that would complete
> apis.plone.org for instance. (If I was not involved in other projects at
> this time I would probably go ahead and start something up on the top of
> plone code to demonstrate it. ;-) )
>
> Any opinions about that ?

I think Sphinx can work for developer documentation. I don't think it
works well for end-user documentation. For that, we have a CMS already. :)

I'm not a huge fan of reST myself, but I know many people like it. We
can probably standardise our way of writing documentation for packages,
and if we can pull in interface definitions and docstrings, then having
a "live" browsable set of documentation would be nice.

One problem is how we integrate this into our existing documentation
area. I know that grok.zope.org and new.zope.org have similar problems.
Since both use Plone, we could conceivably find a solution together.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Tarek Ziadé

Re: Sphinx for Plone doc ?

Reply Threaded

Martin Aspeli wrote:

I think Sphinx can work for developer documentation. I don't think it
works well for end-user documentation. For that, we have a CMS already. :)

I think the only advantage of a CMS at this time for such static document is the comments
user can add.

This is being added in Sphinx iirc. In any case, the current documentation area is quite nice already, so I agree it would fit better for developer documentation.

Martin Aspeli wrote:

I'm not a huge fan of reST myself, but I know many people like it. We
can probably standardise our way of writing documentation for packages,
and if we can pull in interface definitions and docstrings, then having
a "live" browsable set of documentation would be nice.

Yes, Sphinx has an autodoc feature that browse packages looking
for reSt file, so it should be easy to set it up

Martin Aspeli wrote:

One problem is how we integrate this into our existing documentation
area. I know that grok.zope.org and new.zope.org have similar problems.
Since both use Plone, we could conceivably find a solution together.

Yes, this is a problem. Maybe having a separate site (like apis.plone.org)
dedicated to sphinx autodoc generation for all packages could be a starting point.

cheers
Tarek

Martin Aspeli-2

Re: Sphinx for Plone doc ?

Reply Threaded

Tarek Ziadé wrote:

>
>
> Martin Aspeli wrote:
>> I think Sphinx can work for developer documentation. I don't think it
>> works well for end-user documentation. For that, we have a CMS already. :)
>>
>
> I think the only advantage of a CMS at this time for such static document is
> the comments
> user can add.

I'm not so sure about that. The current PHC architecture (well, once you
guys finish fixing plone.org) makes it easy for people to contribute
documentation. We get a review workflow, and we get content types that
make it easy to manage images, file attachments and multiple pages. I
consider this type of editing environment much more conducive to good
documentation than reST in svn. Most people are not comfortable with
reST because it's not WYSIWYG. It's very geeky. :)

> This is being added in Sphinx iirc. In any case, the current documentation
> area is quite nice already, so I agree it would fit better for developer
> documentation.

Right. And keeping the docs close to the source is a very good idea. I
think the dream would be to be able to publish doctests, readmes and
interface docs in a seamlessly browsable environment that's easy to keep
up to date, and which can cover core plone packages as well as third
party packages.

More general tutorials, how-tos and reference manuals should probably
stay in Plone, IMHO.

> Yes, this is a problem. Maybe having a separate site (like apis.plone.org)
> dedicated to sphinx autodoc generation for all packages could be a starting
> point.

I think that's certainly an easy place to begin. We obviously have
api.plone.org now, but I'm not sure how many people use it. Sphinx would
probably make it much more friendly.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-3

Re: Sphinx for Plone doc ?

Reply Threaded

Martin Aspeli wrote:

> Tarek Ziadé wrote:
>>
>> Martin Aspeli wrote:
>>> I think Sphinx can work for developer documentation. I don't think it
>>> works well for end-user documentation. For that, we have a CMS already. :)
>>>
>> I think the only advantage of a CMS at this time for such static document is
>> the comments
>> user can add.
>
> I'm not so sure about that. The current PHC architecture (well, once you
> guys finish fixing plone.org) makes it easy for people to contribute
> documentation. We get a review workflow, and we get content types that
> make it easy to manage images, file attachments and multiple pages. I
> consider this type of editing environment much more conducive to good
> documentation than reST in svn. Most people are not comfortable with
> reST because it's not WYSIWYG. It's very geeky. :)
>
>> This is being added in Sphinx iirc. In any case, the current documentation
>> area is quite nice already, so I agree it would fit better for developer
>> documentation.
>
> Right. And keeping the docs close to the source is a very good idea. I
> think the dream would be to be able to publish doctests, readmes and
> interface docs in a seamlessly browsable environment that's easy to keep
> up to date, and which can cover core plone packages as well as third
> party packages.

I think a key difference is that IMO PHC promotes lots of versions of
documentation. Each tutorial is an island created by one person at one
time.
I'm not sure how sphinx works but the end result looks more like a
cohesive explanation of how stuff works and fits togeather. What is
their update process?
Hopefully the missing piece for PHC is editors to make the individual
submissions into a whole.

> More general tutorials, how-tos and reference manuals should probably
> stay in Plone, IMHO.
>
>> Yes, this is a problem. Maybe having a separate site (like apis.plone.org)
>> dedicated to sphinx autodoc generation for all packages could be a starting
>> point.
>
> I think that's certainly an easy place to begin. We obviously have
> api.plone.org now, but I'm not sure how many people use it. Sphinx would
> probably make it much more friendly.

The good thing about api documentation is you know its up to date or at
least linked to a certain version. But then only those who can write
framework code can write the documentation right... with the current
api.plone.org?

Certainly doing what they have done and having versions of their docs
linked to teh products version is the way to go I think.

> Martin
>

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Martin Aspeli-2

Re: Sphinx for Plone doc ?

Reply Threaded

Hi Dylan,

> I think a key difference is that IMO PHC promotes lots of versions of
> documentation. Each tutorial is an island created by one person at one
> time.

True, but likely so is a file in svn. :)

> I'm not sure how sphinx works but the end result looks more like a
> cohesive explanation of how stuff works and fits togeather. What is
> their update process?

Sphinx just generates HTML from reST files associated with packages.
That's why it works well for developer/low-level documentation. I write
readme's and doctests for my packages, and Sphinx makes them accessible
in a nice way.

> Hopefully the missing piece for PHC is editors to make the individual
> submissions into a whole.

Right. The current documentation isn't suffering from a technology
problem, it's suffering (less than it used to, it must be said) from the
all too familiar problem that to a lot of people, writing documentation
is not as fun as writing code, and updating and editing documentation is
even more onerous.

For example, I doubt we'd get Laura or JoAnna or Donna to write
documentation in reST in svn. Not because they couldn't, but because
that kind of environment isn't geared for that type of user or that type
of documentation. Even figuring out where to put it would be awkward.
reST is awkward. Lack of WYSIWYG is awkward.

And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
to write documentation for their packages in the PHC, although they do
often write excellent developer documentation that's embedded with the
code. Sphinx could let us make that more accessible to people. I don't
think it'll solve any other problems for us.

> Certainly doing what they have done and having versions of their docs
> linked to teh products version is the way to go I think.

Yep.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-3

Re: Sphinx for Plone doc ?

Reply Threaded

I didn't make myself very clear.

Absolutely agree that a CMS is the most accessible way to help people
make documentation.
One thing that api docs do is show 1 document per part of the system,
all togeather for a single version. http://www.python.org/doc/versions/
Hopefully thats something that editors can do with the PHC. Create one
up to date consistent version of the docs for the current version, and
relegate old docs to old versions so its clear they are obsolete.

Martin Aspeli wrote:

> Hi Dylan,
>
>> I think a key difference is that IMO PHC promotes lots of versions of
>> documentation. Each tutorial is an island created by one person at one
>> time.
>
> True, but likely so is a file in svn. :)
>
>> I'm not sure how sphinx works but the end result looks more like a
>> cohesive explanation of how stuff works and fits togeather. What is
>> their update process?
>
> Sphinx just generates HTML from reST files associated with packages.
> That's why it works well for developer/low-level documentation. I write
> readme's and doctests for my packages, and Sphinx makes them accessible
> in a nice way.
>
>> Hopefully the missing piece for PHC is editors to make the individual
>> submissions into a whole.
>
> Right. The current documentation isn't suffering from a technology
> problem, it's suffering (less than it used to, it must be said) from the
> all too familiar problem that to a lot of people, writing documentation
> is not as fun as writing code, and updating and editing documentation is
> even more onerous.
>
> For example, I doubt we'd get Laura or JoAnna or Donna to write
> documentation in reST in svn. Not because they couldn't, but because
> that kind of environment isn't geared for that type of user or that type
> of documentation. Even figuring out where to put it would be awkward.
> reST is awkward. Lack of WYSIWYG is awkward.
>
> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> to write documentation for their packages in the PHC, although they do
> often write excellent developer documentation that's embedded with the
> code. Sphinx could let us make that more accessible to people. I don't
> think it'll solve any other problems for us.
>
>> Certainly doing what they have done and having versions of their docs
>> linked to teh products version is the way to go I think.
>
> Yep.
>
> Martin
>
>

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wichert Akkerman

Re: Sphinx for Plone doc ?

Reply Threaded

Previously Dylan Jay wrote:

> Martin Aspeli wrote:
> > Hi Dylan,
> >
> >> I think a key difference is that IMO PHC promotes lots of versions of
> >> documentation. Each tutorial is an island created by one person at one
> >> time.
> >
> > True, but likely so is a file in svn. :)
> >
> >> I'm not sure how sphinx works but the end result looks more like a
> >> cohesive explanation of how stuff works and fits togeather. What is
> >> their update process?
> >
> > Sphinx just generates HTML from reST files associated with packages.
> > That's why it works well for developer/low-level documentation. I write
> > readme's and doctests for my packages, and Sphinx makes them accessible
> > in a nice way.
> >
> >> Hopefully the missing piece for PHC is editors to make the individual
> >> submissions into a whole.
> >
> > Right. The current documentation isn't suffering from a technology
> > problem, it's suffering (less than it used to, it must be said) from the
> > all too familiar problem that to a lot of people, writing documentation
> > is not as fun as writing code, and updating and editing documentation is
> > even more onerous.
> >
> > For example, I doubt we'd get Laura or JoAnna or Donna to write
> > documentation in reST in svn. Not because they couldn't, but because
> > that kind of environment isn't geared for that type of user or that type
> > of documentation. Even figuring out where to put it would be awkward.
> > reST is awkward. Lack of WYSIWYG is awkward.
> >
> > And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> > to write documentation for their packages in the PHC, although they do
> > often write excellent developer documentation that's embedded with the
> > code. Sphinx could let us make that more accessible to people. I don't
> > think it'll solve any other problems for us.

Which immediately makes me conclude that Sphinx would be ideal to build
reference documentation (which do don't have at all right now) while PHC
is great for other types of documentation.

Developers need to do a much better job of writing reference
documentation for the code they write.
http://pypi.python.org/pypi/plone.portlets is useless for example, while
http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
get away with it I'm tempted to make it a hard requirement for
everything that gets merged for Plone 4.

Wichert.

--
Wichert Akkerman <wichert@...> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Martin Aspeli-2

Re: Sphinx for Plone doc ?

Reply Threaded

Wichert Akkerman wrote:

> Previously Dylan Jay wrote:
>> Martin Aspeli wrote:
>>> Hi Dylan,
>>>
>>>> I think a key difference is that IMO PHC promotes lots of versions of
>>>> documentation. Each tutorial is an island created by one person at one
>>>> time.
>>> True, but likely so is a file in svn. :)
>>>
>>>> I'm not sure how sphinx works but the end result looks more like a
>>>> cohesive explanation of how stuff works and fits togeather. What is
>>>> their update process?
>>> Sphinx just generates HTML from reST files associated with packages.
>>> That's why it works well for developer/low-level documentation. I write
>>> readme's and doctests for my packages, and Sphinx makes them accessible
>>> in a nice way.
>>>
>>>> Hopefully the missing piece for PHC is editors to make the individual
>>>> submissions into a whole.
>>> Right. The current documentation isn't suffering from a technology
>>> problem, it's suffering (less than it used to, it must be said) from the
>>> all too familiar problem that to a lot of people, writing documentation
>>> is not as fun as writing code, and updating and editing documentation is
>>> even more onerous.
>>>
>>> For example, I doubt we'd get Laura or JoAnna or Donna to write
>>> documentation in reST in svn. Not because they couldn't, but because
>>> that kind of environment isn't geared for that type of user or that type
>>> of documentation. Even figuring out where to put it would be awkward.
>>> reST is awkward. Lack of WYSIWYG is awkward.
>>>
>>> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
>>> to write documentation for their packages in the PHC, although they do
>>> often write excellent developer documentation that's embedded with the
>>> code. Sphinx could let us make that more accessible to people. I don't
>>> think it'll solve any other problems for us.
>
> Which immediately makes me conclude that Sphinx would be ideal to build
> reference documentation (which do don't have at all right now) while PHC
> is great for other types of documentation.
>
> Developers need to do a much better job of writing reference
> documentation for the code they write.
> http://pypi.python.org/pypi/plone.portlets is useless for example, while
> http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
> get away with it I'm tempted to make it a hard requirement for
> everything that gets merged for Plone 4.

Heh, point taken. If I put the plone.portlets doctest into pypi, you may
be a bit scared, though. ;-)

I think making this a requirement for new packages is a good idea, so
long as we don't become overly draconian about it.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

JoAnna Springsteen

Re: Sphinx for Plone doc ?

Reply Threaded

In reply to this post by Wichert Akkerman

>
>>>
>>>
>>>
>>>
>>>
> Which immediately makes me conclude that Sphinx would be ideal to
> build
> reference documentation (which do don't have at all right now) while
> PHC
> is great for other types of documentation.
>
> Developers need to do a much better job of writing reference
> documentation for the code they write.
> http://pypi.python.org/pypi/plone.portlets is useless for example,
> while
> http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
> get away with it I'm tempted to make it a hard requirement for
> everything that gets merged for Plone 4.

Hmmm. Getting developers to write more reference docs.... Sounds like
a good conference disscussion to me. If you guys think it's worth a
conf talk, I'll organize a panel talk if people agree to be on the
panel. Might get us some good ideas and a way to move forward. While
you're right that most of the doc team wouldnt use reST, anything that
gets devs documenting is worth a shot in my book.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wichert Akkerman

Re: Sphinx for Plone doc ?

Reply Threaded

In reply to this post by Martin Aspeli-2

Previously Martin Aspeli wrote:

> Wichert Akkerman wrote:
> > Previously Dylan Jay wrote:
> >> Martin Aspeli wrote:
> >>> Hi Dylan,
> >>>
> >>>> I think a key difference is that IMO PHC promotes lots of versions of
> >>>> documentation. Each tutorial is an island created by one person at one
> >>>> time.
> >>> True, but likely so is a file in svn. :)
> >>>
> >>>> I'm not sure how sphinx works but the end result looks more like a
> >>>> cohesive explanation of how stuff works and fits togeather. What is
> >>>> their update process?
> >>> Sphinx just generates HTML from reST files associated with packages.
> >>> That's why it works well for developer/low-level documentation. I write
> >>> readme's and doctests for my packages, and Sphinx makes them accessible
> >>> in a nice way.
> >>>
> >>>> Hopefully the missing piece for PHC is editors to make the individual
> >>>> submissions into a whole.
> >>> Right. The current documentation isn't suffering from a technology
> >>> problem, it's suffering (less than it used to, it must be said) from the
> >>> all too familiar problem that to a lot of people, writing documentation
> >>> is not as fun as writing code, and updating and editing documentation is
> >>> even more onerous.
> >>>
> >>> For example, I doubt we'd get Laura or JoAnna or Donna to write
> >>> documentation in reST in svn. Not because they couldn't, but because
> >>> that kind of environment isn't geared for that type of user or that type
> >>> of documentation. Even figuring out where to put it would be awkward.
> >>> reST is awkward. Lack of WYSIWYG is awkward.
> >>>
> >>> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> >>> to write documentation for their packages in the PHC, although they do
> >>> often write excellent developer documentation that's embedded with the
> >>> code. Sphinx could let us make that more accessible to people. I don't
> >>> think it'll solve any other problems for us.
> >
> > Which immediately makes me conclude that Sphinx would be ideal to build
> > reference documentation (which do don't have at all right now) while PHC
> > is great for other types of documentation.
> >
> > Developers need to do a much better job of writing reference
> > documentation for the code they write.
> > http://pypi.python.org/pypi/plone.portlets is useless for example, while
> > http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
> > get away with it I'm tempted to make it a hard requirement for
> > everything that gets merged for Plone 4.
>
> Heh, point taken. If I put the plone.portlets doctest into pypi, you may
> be a bit scared, though. ;-)

A doctest is a test, it is often not very useful as user documentation
or reference documentation but more a document describing implementation
details and corner case. Still, it's a hell of a lot better than nothing
at all :)

Wichert.

--
Wichert Akkerman <wichert@...> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-3

Re: Sphinx for Plone doc ?

Reply Threaded

In reply to this post by Wichert Akkerman

Wichert Akkerman wrote:

I'd like to see a consistent set of PHC docs combined with api type
reference docs from the code in such a way that they were released in
conjunction with plone releases (of course there might have to be a lag)

e.g. The plone 3.1 docs. The plone 3.0 docs. The plone 3.5 docs.

That might mean for each release the editors of each PHC section
selecting a subset of the tutorials etc that togeather make an
up-to-date and *consistent* set of documentation to represent that
release. Its all tagged and is then available at a url that indicates
which release it belongs to.

What I mean by consistent is tutorials/howtos etc that don't contradict
each other or make confusingly different suggestions on the approach to
solve problems.

Technically how this happens I don't know since I seem to be suggesting
that PHC items are copied and then archived for each release, or perhaps
using iterate. and also that api docs prob have to be brought into PHC
to participate in that same versioning process.

or perhaps its easier if PHC content is versioned into svn along with
the api docs and then all published statically. But then you'd need
links back to plone docs comments and the "live" plone docs for
encouraging new doc submissions.

Dylan.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wichert Akkerman

Re: Sphinx for Plone doc ?

Reply Threaded

Previously Dylan Jay wrote:

> Wichert Akkerman wrote:
> > Previously Dylan Jay wrote:
> >> Martin Aspeli wrote:
> >>> Hi Dylan,
> >>>
> >>>> I think a key difference is that IMO PHC promotes lots of versions of
> >>>> documentation. Each tutorial is an island created by one person at one
> >>>> time.
> >>> True, but likely so is a file in svn. :)
> >>>
> >>>> I'm not sure how sphinx works but the end result looks more like a
> >>>> cohesive explanation of how stuff works and fits togeather. What is
> >>>> their update process?
> >>> Sphinx just generates HTML from reST files associated with packages.
> >>> That's why it works well for developer/low-level documentation. I write
> >>> readme's and doctests for my packages, and Sphinx makes them accessible
> >>> in a nice way.
> >>>
> >>>> Hopefully the missing piece for PHC is editors to make the individual
> >>>> submissions into a whole.
> >>> Right. The current documentation isn't suffering from a technology
> >>> problem, it's suffering (less than it used to, it must be said) from the
> >>> all too familiar problem that to a lot of people, writing documentation
> >>> is not as fun as writing code, and updating and editing documentation is
> >>> even more onerous.
> >>>
> >>> For example, I doubt we'd get Laura or JoAnna or Donna to write
> >>> documentation in reST in svn. Not because they couldn't, but because
> >>> that kind of environment isn't geared for that type of user or that type
> >>> of documentation. Even figuring out where to put it would be awkward.
> >>> reST is awkward. Lack of WYSIWYG is awkward.
> >>>
> >>> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> >>> to write documentation for their packages in the PHC, although they do
> >>> often write excellent developer documentation that's embedded with the
> >>> code. Sphinx could let us make that more accessible to people. I don't
> >>> think it'll solve any other problems for us.
> >
> > Which immediately makes me conclude that Sphinx would be ideal to build
> > reference documentation (which do don't have at all right now) while PHC
> > is great for other types of documentation.
>
> I'd like to see a consistent set of PHC docs combined with api type
> reference docs from the code in such a way that they were released in
> conjunction with plone releases (of course there might have to be a lag)
>
> e.g. The plone 3.1 docs. The plone 3.0 docs. The plone 3.5 docs.
>
> That might mean for each release the editors of each PHC section
> selecting a subset of the tutorials etc that togeather make an
> up-to-date and *consistent* set of documentation to represent that
> release. Its all tagged and is then available at a url that indicates
> which release it belongs to.

That will never happen unless we magically increase the number of people
working on documentation by a factor of 10.

It may be interesting to read the grok-dev archive for the last month or
so. Grok is moving in exactly this direction: sphinx-based reference
documentation which is maintained in svn and has separate branches for
the separate grok releases combined with tutorials in PHC. Both are
shown on grok.zope.org.

Wichert.

--
Wichert Akkerman <wichert@...> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

vedaw

Re: Sphinx for Plone doc ?

Reply Threaded

In reply to this post by Dylan Jay-3

I think we can at least work surfacing the docs based on version number
through views. I've put together a design for the plone.org/products section
that utilizes this concept, and the hope was that the view that breaks out
these versions could be re-used for the docs section as well.

This is a policy change that SteveM and I have been chatting about but we
hadn't gotten to a decision or to the implementation stage. I personally
like the idea, and it means that the currently supported versions (2.5 and
3.0, plus older docs) are split out but still available.

As for making tutorials, etc. not contradict each other, a lot of that will
ride on having people on the docs team garden properly. I think it would
also behoove us to beef up the manuals to be the core set of docs with
tutorials and how-tos being utilized for unusual use cases and "real world"
examples. When a new version of Plone comes out, we just copy the old manual
and revise as needed. That will reduce maintenance and focus the
documentation better.

I can't really speak to how the api docs would fit in here, but if you can
define better what it is you hope to see, perhaps someone will volunteer to
do the work.

- Veda

On 7/6/08 7:06 PM, "Dylan Jay" <gmane@...> wrote:

>
> I'd like to see a consistent set of PHC docs combined with api type
> reference docs from the code in such a way that they were released in
> conjunction with plone releases (of course there might have to be a lag)
>
> e.g. The plone 3.1 docs. The plone 3.0 docs. The plone 3.5 docs.
>
> That might mean for each release the editors of each PHC section
> selecting a subset of the tutorials etc that togeather make an
> up-to-date and *consistent* set of documentation to represent that
> release. Its all tagged and is then available at a url that indicates
> which release it belongs to.
>
> What I mean by consistent is tutorials/howtos etc that don't contradict
> each other or make confusingly different suggestions on the approach to
> solve problems.