This came up in the comments around #314 but I'm of the opinion that autoqa-devel is a better place for this conversation.
How do we want to be doing documentation? At the moment, we're kind of spread across the fp.o wiki and the fedorahosted trac wiki and I agree with Kamil that we should probably start giving some thought to how our documentation is organized.
Personally, I'm of the opinion that the fp.o wiki is not the best place for most of our documentation. Some of it, yes (project overview, some test documentation maybe) but not most of it. I'm looking at bodhi [1] as an example where most of their docs are not in the fp.o wiki.
Taking this one step farther, my ideal preference would be to keep the docs with the code so that the lions share of our docs are in git and generated at build time (updated on push to master once we get CI implemented). I think that py.test [2] is a great example of doing this and I find their documentation well written and easy to follow (created with sphinx [3]). Granted, the tool is only part of that but I think that having things in one place and not handicapping ourselves with wiki syntax and "tools" (finding and changing occurrences are easier) would be a decent start towards better docs.
Thoughts? Anything I missed?
Tim
PS I'm not proposing we change anything immediately, just thoughts for going forward
[1] https://fedorahosted.org/bodhi/ [2] http://doc.pytest.org/en/latest/ [3] http://sphinx.pocoo.org/
Thanks for starting this conversation! Some thoughts below ...
On Thu, 2011-06-16 at 08:27 -0600, Tim Flink wrote:
This came up in the comments around #314 but I'm of the opinion that autoqa-devel is a better place for this conversation.
How do we want to be doing documentation? At the moment, we're kind of spread across the fp.o wiki and the fedorahosted trac wiki and I agree with Kamil that we should probably start giving some thought to how our documentation is organized.
Personally, I'm of the opinion that the fp.o wiki is not the best place for most of our documentation. Some of it, yes (project overview, some test documentation maybe) but not most of it. I'm looking at bodhi [1] as an example where most of their docs are not in the fp.o wiki.
Taking this one step farther, my ideal preference would be to keep the docs with the code so that the lions share of our docs are in git and generated at build time (updated on push to master once we get CI implemented). I think that py.test [2] is a great example of doing this and I find their documentation well written and easy to follow (created with sphinx [3]). Granted, the tool is only part of that but I think that having things in one place and not handicapping ourselves with wiki syntax and "tools" (finding and changing occurrences are easier) would be a decent start towards better docs.
Thoughts? Anything I missed?
Tim
PS I'm not proposing we change anything immediately, just thoughts for going forward
I like having the docs more tightly coupled with the code. I've seen several approaches that work well as long as they're consistently used. One approach, as you suggest, where the docs live in the code and are pushed out to a presentation layer. Another, where the docs live on the wiki, and are pulled down with the code during packaging (anaconda). Certainly a personal preference, they both work just so long as things are consistent.
If the docs live with the code, what formats are acceptable? Do the docs have to be plain/text at that point, or can they include mark-up?
When it comes to mark-up, I do like fp.o/wiki mediawiki syntax *much* better than TRAC wiki. TRAC wiki syntax is rough (imo) and the history tracking doesn't seem very robust. I've just spent more time doing fp.o/wiki work so I'm clearly more comfortable with that approach. I'm certainly willing to try something different, but editing in TRAC makes me cringe.
Thanks, James
On Thu, 16 Jun 2011 10:38:48 -0400 James Laska jlaska@redhat.com wrote:
I like having the docs more tightly coupled with the code. I've seen several approaches that work well as long as they're consistently used. One approach, as you suggest, where the docs live in the code and are pushed out to a presentation layer. Another, where the docs live on the wiki, and are pulled down with the code during packaging (anaconda). Certainly a personal preference, they both work just so long as things are consistent.
I didn't think about doing that. Personally, I would prefer keeping everything in the same place instead of requiring network access every time that the docs are built but I agree that the important part is to be consistent and have better coupling.
If the docs live with the code, what formats are acceptable? Do the docs have to be plain/text at that point, or can they include mark-up?
Sphinx works mostly with ReStructuredText [1] which allows for markup that (in my opinion) is much more flexible and powerful than wiki syntax. I think of it kind of like a simplified LaTeX without the brutal learning curve. You can see the rST source on most sphinx generated pages ([2] is an example)
[1] http://docutils.sourceforge.net/rst.html [2] http://doc.pytest.org/en/latest/_sources/index.txt
When it comes to mark-up, I do like fp.o/wiki mediawiki syntax *much* better than TRAC wiki. TRAC wiki syntax is rough (imo) and the history tracking doesn't seem very robust. I've just spent more time doing fp.o/wiki work so I'm clearly more comfortable with that approach. I'm certainly willing to try something different, but editing in TRAC makes me cringe.
The funny thing is that I'm pretty much the exact opposite. I'm not a huge fan of most wiki dialects and I really don't like using mediawiki unless I have to. I find trac's moin-ish syntax to be one of the more pleasant wiki dialects to work with and their rendering engine seems (to me, at least) to be less bone-headed and less prone to break formatting than most wiki engines. Then again, I think that trac was the first wiki I spent a lot of time with. You are absolutely correct on the history tracking part, though.
A lot of this gets down to personal preference. I may not like mediawiki and my vote would be for other tools but I think it's more important to be consistent and have well written documentation. The ability for others to understand and follow our docs supersedes my tool preferences :)
Tim
----- Original Message -----
From: "Tim Flink" tflink@redhat.com To: autoqa-devel@lists.fedorahosted.org Sent: Thursday, June 16, 2011 11:05:11 PM Subject: Re: AutoQA Documentation On Thu, 16 Jun 2011 10:38:48 -0400 James Laska jlaska@redhat.com wrote:
I like having the docs more tightly coupled with the code. I've seen several approaches that work well as long as they're consistently used. One approach, as you suggest, where the docs live in the code and are pushed out to a presentation layer. Another, where the docs live on the wiki, and are pulled down with the code during packaging (anaconda). Certainly a personal preference, they both work just so long as things are consistent.
I didn't think about doing that. Personally, I would prefer keeping everything in the same place instead of requiring network access every time that the docs are built but I agree that the important part is to be consistent and have better coupling.
If the docs live with the code, what formats are acceptable? Do the docs have to be plain/text at that point, or can they include mark-up?
Sphinx works mostly with ReStructuredText [1] which allows for markup that (in my opinion) is much more flexible and powerful than wiki syntax. I think of it kind of like a simplified LaTeX without the brutal learning curve. You can see the rST source on most sphinx generated pages ([2] is an example)
[1] http://docutils.sourceforge.net/rst.html [2] http://doc.pytest.org/en/latest/_sources/index.txt
When it comes to mark-up, I do like fp.o/wiki mediawiki syntax *much* better than TRAC wiki. TRAC wiki syntax is rough (imo) and the history tracking doesn't seem very robust. I've just spent more time doing fp.o/wiki work so I'm clearly more comfortable with that approach. I'm certainly willing to try something different, but editing in TRAC makes me cringe.
The funny thing is that I'm pretty much the exact opposite. I'm not a huge fan of most wiki dialects and I really don't like using mediawiki unless I have to. I find trac's moin-ish syntax to be one of the more pleasant wiki dialects to work with and their rendering engine seems (to me, at least) to be less bone-headed and less prone to break formatting than most wiki engines. Then again, I think that trac was the first wiki I spent a lot of time with. You are absolutely correct on the history tracking part, though.
A lot of this gets down to personal preference. I may not like mediawiki and my vote would be for other tools but I think it's more important to be consistent and have well written documentation. The ability for others to understand and follow our docs supersedes my tool preferences :)
Tim
Hi, All
For our AutoQA code released, I prefer to use EpyDoc http://epydoc.sourceforge.net/ to document them, It will help others to understand. For other documents I think It is better to create a portal in the wiki, or it is really not easy to find the document when you do not know it.
Hongqing
On Thu, 16 Jun 2011 22:37:57 -0400 (EDT) Hongqing Yang hoyang@redhat.com wrote:
Hi, All
For our AutoQA code released, I prefer to use EpyDoc http://epydoc.sourceforge.net/ to document them, It will help others to understand. For other documents I think It is better to create a portal in the wiki, or it is really not easy to find the document when you do not know it.
Out of curiosity, why epydoc over sphynx with autodoc [1] and/or autosummary [2]?
My concern about epydoc is that it doesn't seem to be changing much anymore. According to sourceforge, there haven't been any commits in the last year and no releases since January, 2008.
From what I understand Sphinx wouldn't be quite as automatic as epydoc but it is a lot more flexible since it doesn't enforce the javadoc like tree structure of the docs.
Do you think that splitting up API documentation from the other docs is better than keeping them together, and having a main page or am I misunderstanding what you mean by a portal?
Tim
[1] http://sphinx.pocoo.org/ext/autodoc.html [2] http://sphinx.pocoo.org/ext/autosummary.html
----- Original Message -----
From: "Tim Flink" tflink@redhat.com To: autoqa-devel@lists.fedorahosted.org Sent: Friday, June 17, 2011 1:27:09 PM Subject: Re: AutoQA Documentation On Thu, 16 Jun 2011 22:37:57 -0400 (EDT) Hongqing Yang hoyang@redhat.com wrote:
Hi, All
For our AutoQA code released, I prefer to use EpyDoc http://epydoc.sourceforge.net/ to document them, It will help others to understand. For other documents I think It is better to create a portal in the wiki, or it is really not easy to find the document when you do not know it.
Out of curiosity, why epydoc over sphynx with autodoc [1] and/or autosummary [2]?
My concern about epydoc is that it doesn't seem to be changing much anymore. According to sourceforge, there haven't been any commits in the last year and no releases since January, 2008.
From what I understand Sphinx wouldn't be quite as automatic as epydoc but it is a lot more flexible since it doesn't enforce the javadoc like tree structure of the docs.
Do you think that splitting up API documentation from the other docs is better than keeping them together, and having a main page or am I misunderstanding what you mean by a portal?
Tim
[1] http://sphinx.pocoo.org/ext/autodoc.html [2] http://sphinx.pocoo.org/ext/autosummary.html
Hi Tim,
I have not explored the sphynx, we can compare these.
The portal here is the same meaning with main page, the purpose is that the users can follow links to the contents like Content Management System.
Hongqing
On Fri, 17 Jun 2011 01:39:22 -0400 (EDT) Hongqing Yang hoyang@redhat.com wrote:
----- Original Message -----
From: "Tim Flink" tflink@redhat.com To: autoqa-devel@lists.fedorahosted.org Sent: Friday, June 17, 2011 1:27:09 PM Subject: Re: AutoQA Documentation On Thu, 16 Jun 2011 22:37:57 -0400 (EDT) Hongqing Yang hoyang@redhat.com wrote:
Hi, All
For our AutoQA code released, I prefer to use EpyDoc http://epydoc.sourceforge.net/ to document them, It will help others to understand. For other documents I think It is better to create a portal in the wiki, or it is really not easy to find the document when you do not know it.
Out of curiosity, why epydoc over sphynx with autodoc [1] and/or autosummary [2]?
My concern about epydoc is that it doesn't seem to be changing much anymore. According to sourceforge, there haven't been any commits in the last year and no releases since January, 2008.
From what I understand Sphinx wouldn't be quite as automatic as epydoc but it is a lot more flexible since it doesn't enforce the javadoc like tree structure of the docs.
Do you think that splitting up API documentation from the other docs is better than keeping them together, and having a main page or am I misunderstanding what you mean by a portal?
Tim
[1] http://sphinx.pocoo.org/ext/autodoc.html [2] http://sphinx.pocoo.org/ext/autosummary.html
Hi Tim,
I have not explored the sphynx, we can compare these.
The portal here is the same meaning with main page, the purpose is that the users can follow links to the contents like Content Management System.
Would the front pages of the online python docs [1] or py.test [2] fit with what you were thinking of?
I think that you're probably right, a comparison would be useful. I don't have a whole lot of experience with either tool - I've worked more with doxygen and javadoc.
Tim
[1] http://docs.python.org/ [2] http://doc.pytest.org/en/latest/
On 06/16/2011 08:38 AM, James Laska wrote:
Thanks for starting this conversation! Some thoughts below ...
On Thu, 2011-06-16 at 08:27 -0600, Tim Flink wrote:
This came up in the comments around #314 but I'm of the opinion that autoqa-devel is a better place for this conversation.
How do we want to be doing documentation? At the moment, we're kind of spread across the fp.o wiki and the fedorahosted trac wiki and I agree with Kamil that we should probably start giving some thought to how our documentation is organized.
Personally, I'm of the opinion that the fp.o wiki is not the best place for most of our documentation. Some of it, yes (project overview, some test documentation maybe) but not most of it. I'm looking at bodhi [1] as an example where most of their docs are not in the fp.o wiki.
Taking this one step farther, my ideal preference would be to keep the docs with the code so that the lions share of our docs are in git and generated at build time (updated on push to master once we get CI implemented). I think that py.test [2] is a great example of doing this and I find their documentation well written and easy to follow (created with sphinx [3]). Granted, the tool is only part of that but I think that having things in one place and not handicapping ourselves with wiki syntax and "tools" (finding and changing occurrences are easier) would be a decent start towards better docs.
Thoughts? Anything I missed?
Tim
PS I'm not proposing we change anything immediately, just thoughts for going forward
I like having the docs more tightly coupled with the code. I've seen several approaches that work well as long as they're consistently used. One approach, as you suggest, where the docs live in the code and are pushed out to a presentation layer. Another, where the docs live on the wiki, and are pulled down with the code during packaging (anaconda). Certainly a personal preference, they both work just so long as things are consistent.
If the docs live with the code, what formats are acceptable? Do the docs have to be plain/text at that point, or can they include mark-up?
When it comes to mark-up, I do like fp.o/wiki mediawiki syntax *much* better than TRAC wiki. TRAC wiki syntax is rough (imo) and the history tracking doesn't seem very robust. I've just spent more time doing fp.o/wiki work so I'm clearly more comfortable with that approach. I'm certainly willing to try something different, but editing in TRAC makes me cringe.
Resurrecting a month old thread in the hopes that we can get some of this figured out.
Any thoughts on the whole mediawiki vs trac vs sphinx vs epydoc vs notes-tied-to-carrier-pidgin question?
Tim
Resurrecting a month old thread in the hopes that we can get some of this figured out.
Any thoughts on the whole mediawiki vs trac vs sphinx vs epydoc vs notes-tied-to-carrier-pidgin question?
Tim
Tim, I like the Sphinx idea. As you stated in your email, the learning curve is a little steep, but overall it looks like it does a good job. Of course, I'm all for as much automation as possible for things like this, you know? I wonder if there is a way to pull from the commit log to do some of this stuff?
John.
PS. I just don't like writing documentation....
On Tue, 2011-07-12 at 16:10 -0600, Tim Flink wrote:
On 06/16/2011 08:38 AM, James Laska wrote:
Thanks for starting this conversation! Some thoughts below ...
On Thu, 2011-06-16 at 08:27 -0600, Tim Flink wrote:
This came up in the comments around #314 but I'm of the opinion that autoqa-devel is a better place for this conversation.
How do we want to be doing documentation? At the moment, we're kind of spread across the fp.o wiki and the fedorahosted trac wiki and I agree with Kamil that we should probably start giving some thought to how our documentation is organized.
Personally, I'm of the opinion that the fp.o wiki is not the best place for most of our documentation. Some of it, yes (project overview, some test documentation maybe) but not most of it. I'm looking at bodhi [1] as an example where most of their docs are not in the fp.o wiki.
Taking this one step farther, my ideal preference would be to keep the docs with the code so that the lions share of our docs are in git and generated at build time (updated on push to master once we get CI implemented). I think that py.test [2] is a great example of doing this and I find their documentation well written and easy to follow (created with sphinx [3]). Granted, the tool is only part of that but I think that having things in one place and not handicapping ourselves with wiki syntax and "tools" (finding and changing occurrences are easier) would be a decent start towards better docs.
Thoughts? Anything I missed?
Tim
PS I'm not proposing we change anything immediately, just thoughts for going forward
I like having the docs more tightly coupled with the code. I've seen several approaches that work well as long as they're consistently used. One approach, as you suggest, where the docs live in the code and are pushed out to a presentation layer. Another, where the docs live on the wiki, and are pulled down with the code during packaging (anaconda). Certainly a personal preference, they both work just so long as things are consistent.
If the docs live with the code, what formats are acceptable? Do the docs have to be plain/text at that point, or can they include mark-up?
When it comes to mark-up, I do like fp.o/wiki mediawiki syntax *much* better than TRAC wiki. TRAC wiki syntax is rough (imo) and the history tracking doesn't seem very robust. I've just spent more time doing fp.o/wiki work so I'm clearly more comfortable with that approach. I'm certainly willing to try something different, but editing in TRAC makes me cringe.
Resurrecting a month old thread in the hopes that we can get some of this figured out.
Any thoughts on the whole mediawiki vs trac vs sphinx vs epydoc vs notes-tied-to-carrier-pidgin question?
I like the approach jskladan and kparal suggest in the other thread (e.g. using it for development/library documentation). I'd prefer keeping our user-focused documentation on fp.org/wiki for now. I like the idea of using sphinx/epydoc to replace any use of TRAC wiki documentation. Are there thoughts on where sphinx/epydoc would be hosted? Would we host that (or link to it) on the TRAC instance?
Thanks, James
Are there thoughts on where sphinx/epydoc would be hosted? Would we host that (or link to it) on the TRAC instance?
What about http://autoqa.fedoraproject.org/doc/... ?
If we have something generated (and preferably packaged it as autoqa-doc.rpm), it makes sense to deploy it on our production server.
On Wed, 2011-07-13 at 09:20 -0400, Kamil Paral wrote:
Are there thoughts on where sphinx/epydoc would be hosted? Would we host that (or link to it) on the TRAC instance?
What about http://autoqa.fedoraproject.org/doc/... ?
If we have something generated (and preferably packaged it as autoqa-doc.rpm), it makes sense to deploy it on our production server.
Doh, perfect! This will need some packaging adjustment, but it makes room for a autoqa.conf httpd config which can also offer up a custom 404.
Thanks, James
On 07/13/2011 07:28 AM, James Laska wrote:
On Wed, 2011-07-13 at 09:20 -0400, Kamil Paral wrote:
Are there thoughts on where sphinx/epydoc would be hosted? Would we host that (or link to it) on the TRAC instance?
What about http://autoqa.fedoraproject.org/doc/... ?
If we have something generated (and preferably packaged it as autoqa-doc.rpm), it makes sense to deploy it on our production server.
Doh, perfect! This will need some packaging adjustment, but it makes room for a autoqa.conf httpd config which can also offer up a custom 404.
The other option would be fedorapeople but I'm not sure how well that would work.
It sounds like we're pretty much at quorum, though. I concede defeat and will start moving stuff from trac to the fp.o wiki.
The questions that I still have are:
- Do we want to start generating API docs soon or wait until later?
- Where do we want to hold release planning docs, if we want them? * Planning docs aren't quite the same and trac seems like a good place to hold those with its integration into our ticketing system.
* I suppose that a related question would be whether or not those are worth the effort to create or not.
Tim
The questions that I still have are:
- Do we want to start generating API docs soon or wait until later?
I would say let's have CI first and auto-docs second.
- Where do we want to hold release planning docs, if we want them?
- Planning docs aren't quite the same and trac seems like a good
place to hold those with its integration into our ticketing system.
We can keep the planning docs in Trac, they are not permanent documentation but just short-term documents for us. Or we can create category "AutoQA:Planning" in MW. No strong opinion here. OTOH pages like "AutoQA configuration" should definitely move to MW, similarly as where all the other user documentation currently is.
- I suppose that a related question would be whether or not those
are worth the effort to create or not.
It's slightly easier to find it inside Trac than inside the mailing list archives.
On 07/13/2011 08:24 AM, Kamil Paral wrote:
The questions that I still have are:
- Do we want to start generating API docs soon or wait until
later?
I would say let's have CI first and auto-docs second.
Sounds like a plan to me. I'm certainly not crazy about the idea of manually pushing docs somewhere.
- Where do we want to hold release planning docs, if we want them?
- Planning docs aren't quite the same and trac seems like a good
place to hold those with its integration into our ticketing system.
We can keep the planning docs in Trac, they are not permanent documentation but just short-term documents for us. Or we can create category "AutoQA:Planning" in MW. No strong opinion here.
I have a slight preference for trac because of it's ticket macros in the wiki but either is fine as long as we're consistent.
OTOH pages like "AutoQA configuration" should definitely move to MW, similarly as where all the other user documentation currently is.
What about the rpmguard and initscripts docs that are currently on the trac wiki?
- I suppose that a related question would be whether or not those
are worth the effort to create or not.
It's slightly easier to find it inside Trac than inside the mailing list archives.
Agreed. It's also cleaner to edit than email threads.
Tim
OTOH pages like "AutoQA configuration" should definitely move to MW, similarly as where all the other user documentation currently is.
What about the rpmguard and initscripts docs that are currently on the trac wiki?
initscripts - probably, but that effort is going to be obsolete in 6 months anyway, right?
rpmguard - that is my abandoned child. The home page is OK on Trac, but "List of rpmguard checks" could be probably moved to MW, maybe re-worked into "AutoQA tests/Rpmguard" help page somehow.
autoqa-devel@lists.fedorahosted.org
-
Hongqing Yang -
James Laska -
John Dulaney -
Kamil Paral -
Tim Flink