I've posted a comparison between Sphinx and Dexy [1] - as well as updated the phabricator ticket [2]. The tools are pretty similar in what they can produce, so it really comes down to what people are comfortable with. The learning curve for Dexy isn't steep, and I think it's just enough easier to use compared to Sphinx for our purposes.
I wasn't able to find air-tight reasoning for one over the other for qa-devel work - but found dexy a bit easier to use and template. Source for both tutorials can be found on my bitbucket profile [3].
// Roshi
[1] http://roshi.fedorapeople.org/comparing-dexy-and-sphinx.html [2] https://phab.qadevel.cloud.fedoraproject.org/T39 [3] https://bitbucket.org/Rorosha/doc-tools
I've posted a comparison between Sphinx and Dexy [1] - as well as updated the phabricator ticket [2]. The tools are pretty similar in what they can produce, so it really comes down to what people are comfortable with. The learning curve for Dexy isn't steep, and I think it's just enough easier to use compared to Sphinx for our purposes.
I wondered why I hadn't seen it at Fedora Planet (neither your previous blogpost), and it's because your RSS feed is no longer updated: http://roshi.fedorapeople.org/feeds/fedora.atom.xml
I wasn't able to find air-tight reasoning for one over the other for qa-devel work - but found dexy a bit easier to use and template. Source for both tutorials can be found on my bitbucket profile [3].
Thanks. Can you move it into our team repo list? https://bitbucket.org/fedoraqa
// Roshi
[1] http://roshi.fedorapeople.org/comparing-dexy-and-sphinx.html [2] https://phab.qadevel.cloud.fedoraproject.org/T39 [3] https://bitbucket.org/Rorosha/doc-tools
On Wed, 29 Jan 2014 07:32:29 -0500 (EST) Kamil Paral kparal@redhat.com wrote:
I've posted a comparison between Sphinx and Dexy [1] - as well as updated the phabricator ticket [2]. The tools are pretty similar in what they can produce, so it really comes down to what people are comfortable with. The learning curve for Dexy isn't steep, and I think it's just enough easier to use compared to Sphinx for our purposes.
I wondered why I hadn't seen it at Fedora Planet (neither your previous blogpost), and it's because your RSS feed is no longer updated: http://roshi.fedorapeople.org/feeds/fedora.atom.xml
I wasn't able to find air-tight reasoning for one over the other for qa-devel work - but found dexy a bit easier to use and template. Source for both tutorials can be found on my bitbucket profile [3].
Thanks. Can you move it into our team repo list? https://bitbucket.org/fedoraqa
// Roshi
[1] http://roshi.fedorapeople.org/comparing-dexy-and-sphinx.html [2] https://phab.qadevel.cloud.fedoraproject.org/T39 [3] https://bitbucket.org/Rorosha/doc-tools
qa-devel mailing list qa-devel@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/qa-devel
I've fixed the RSS issue. As for moving the repo - I think it makes more sense to move the tutorial source to taskotron (instead of the team repo list) once we decide the tool we want to use for docs - Unless there's a real need for the demo to be on the team page that I'm not seeing.
// Roshi
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 01/29/2014 02:09 AM, Mike Ruckman wrote:
I've posted a comparison between Sphinx and Dexy [1] - as well as updated the phabricator ticket [2]. The tools are pretty similar in what they can produce, so it really comes down to what people are comfortable with. The learning curve for Dexy isn't steep, and I think it's just enough easier to use compared to Sphinx for our purposes.
I wasn't able to find air-tight reasoning for one over the other for qa-devel work - but found dexy a bit easier to use and template. Source for both tutorials can be found on my bitbucket profile [3].
- From my perspective, the killer feature of using Sphinx for a new project isn't Sphinx itself, but ReadTheDocs: https://readthedocs.org/
Sure, you *can* still host your own docs if you really want to, but RTFD means you can just set up a POST hook on your repo and go. Building draft docs from a development branch or a forked repo is also trivial (handy if you're wanting to make it easy for people to review a proposed theme change, or other major docs refactor without needing to build the docs locally).
The other interesting Sphinx feature I find invaluable when working on CPython, Beaker and my own projects is the flexible autoupdating cross references (including to other projects through the intersphinx extension). Dexy's section-titles-only cross linking capabilities seem like a relatively poor substitute (http://dexy.github.io/dexy-user-guide/#_links_to_pages_and_sections), suffering from the limitations imposed by its agnosticism regarding input formats.
For example, Sphinx doesn't care if different sections use the same title, or if the exact section titles change, so long as they use a unique and consistent reference label. Customising the text used for a cross reference is also trivial (:ref:`this is a cross reference <to-this-label>`). A lot of things are also inherently labelled, so you can do :class:`name` or :func:`name` (with Python, C, C++, JavaScript and REST domains currently supported for that). The glossary feature is also excellent in being able to easily hyperlink term definitions.
More details here: http://sphinx-doc.org/markup/inline.html#cross-referencing-syntax
Cheers, Nick.
- -- Nick Coghlan Red Hat Hosted & Shared Services Software Engineering & Development, Brisbane
Testing Solutions Team Lead Beaker Development Lead (http://beaker-project.org/)
On Thu, 30 Jan 2014 13:35:51 +1000 Nick Coghlan ncoghlan@redhat.com wrote:
<trimmed>
- From my perspective, the killer feature of using Sphinx for a new
project isn't Sphinx itself, but ReadTheDocs: https://readthedocs.org/
Sure, you *can* still host your own docs if you really want to, but RTFD means you can just set up a POST hook on your repo and go. Building draft docs from a development branch or a forked repo is also trivial (handy if you're wanting to make it easy for people to review a proposed theme change, or other major docs refactor without needing to build the docs locally).
I hadn't even considered RTD. I just assumed (bad of me, I know :P) that we'd be hosting our own docs. In a perfect world there'd be one place for documentation - but I don't know how likely that is. Thanks for bringing it up - hadn't occurred to me.
The other interesting Sphinx feature I find invaluable when working on CPython, Beaker and my own projects is the flexible autoupdating cross references (including to other projects through the intersphinx extension). Dexy's section-titles-only cross linking capabilities seem like a relatively poor substitute (http://dexy.github.io/dexy-user-guide/#_links_to_pages_and_sections), suffering from the limitations imposed by its agnosticism regarding input formats.
That's a fair point. Something I didn't have was means for a complete comparison within a project. I merely liked the idea of multiple inputs because it easily incorporates projects in other languages that qa devel might use in the future - but that's far from a actual *reason* to pick it as the tool.
Oh, and nice to meet you Nick :)
// Roshi
<snip>
Cheers, Nick.
Nick Coghlan Red Hat Hosted & Shared Services Software Engineering & Development, Brisbane
Testing Solutions Team Lead Beaker Development Lead (http://beaker-project.org/)
I
On Tue, 28 Jan 2014 09:09:56 -0700 Mike Ruckman roshi@fedoraproject.org wrote:
I've posted a comparison between Sphinx and Dexy [1] - as well as updated the phabricator ticket [2]. The tools are pretty similar in what they can produce, so it really comes down to what people are comfortable with. The learning curve for Dexy isn't steep, and I think it's just enough easier to use compared to Sphinx for our purposes.
I wasn't able to find air-tight reasoning for one over the other for qa-devel work - but found dexy a bit easier to use and template. Source for both tutorials can be found on my bitbucket profile [3].
As mike started the evaluation, the goal was to see which of the two tools would be better for qa-devel (and possibly qa) as a whole and end up with one documentation tool.
As I'm looking through the demo that he came up, adding in my own experience and what nick said about rtd.org, I'm wondering if we really need or want to have a single tool.
As I see it, both sphinx and dexy have their advantages and disadvantages. Sphinx is probably better for documenting a software project and dexy is probably better for more general documentation.
The main general advantage I see to dexy is that it makes theming and customization of output much less painful when we want to make stuff look more fedora-y. However, one of my goals for taskotron is not to restrict it to Fedora and thus, fedora branding for taskotron-specific docs is a bit of an anti-goal.
I have two reasons for wanting to keep taskotron as distro-neutral as reasonably possible:
1. One thing that Kamil said about a year ago now is that there are several interesting automation platforms out there but it's a shame that they're all really purpose-specific. I agree and see no reason to limit taskotron to Fedora from the start - if we can sanely make at least the core bits generic, that'll only increase the possible user/contributor base going forward.
2. For me, one of the overarching lessons from autoqa is that tight coupling leads to pain, lots of pain. AutoQA doesn't really work well for anything but Fedora or outside the production infrastructure. While not directly related, I do see a correlation between keeping the core bits distro agnostic and not repeating some of the problematic parts of autoqa - it forces us to decouple some things and isolate the Fedora specific bits.
With this in mind, I propose that we use sphinx and rtd.org for taskotron and self-hosted dexy for the less structured qadevel landing page which points to various docs and resources.
Thoughts?
Tim
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 01/31/2014 09:55 AM, Tim Flink wrote:
I have two reasons for wanting to keep taskotron as distro-neutral as reasonably possible:
- One thing that Kamil said about a year ago now is that there
are several interesting automation platforms out there but it's a shame that they're all really purpose-specific. I agree and see no reason to limit taskotron to Fedora from the start - if we can sanely make at least the core bits generic, that'll only increase the possible user/contributor base going forward.
- For me, one of the overarching lessons from autoqa is that
tight coupling leads to pain, lots of pain. AutoQA doesn't really work well for anything but Fedora or outside the production infrastructure. While not directly related, I do see a correlation between keeping the core bits distro agnostic and not repeating some of the problematic parts of autoqa - it forces us to decouple some things and isolate the Fedora specific bits.
With this in mind, I propose that we use sphinx and rtd.org for taskotron and self-hosted dexy for the less structured qadevel landing page which points to various docs and resources.
Thoughts?
This sounds like a good plan to me - for building *part* of a site, Sphinx is fine, and as documentation for a particular project, it's great. However, it's not a great overall site construction system - it's designed to document a *thing*, not build a website.
For beaker-project.org, we currently just have some custom HTML pages to stitch together a few different Sphinx projects and other miscellaneous bits and pieces. For new subprojects (like splitting out the beah and beaker-system-scan docs), we're not even doing that - we're just hosting them on ReadTheDocs and linking to them there.
Cheers, Nick.
P.S. If you haven't already, you may want to look at some of the stuff the OpenStack CI folks are doing with Zuul and Gearman. While they're not an alternative in general, some of the trigger and action plugin aspects of Zuul may also be relevant to Taskotron.
- -- Nick Coghlan Red Hat Hosted & Shared Services Software Engineering & Development, Brisbane
Testing Solutions Team Lead Beaker Development Lead (http://beaker-project.org/)
On Thu, 30 Jan 2014 16:55:49 -0700 Tim Flink tflink@redhat.com wrote:
On Tue, 28 Jan 2014 09:09:56 -0700 Mike Ruckman roshi@fedoraproject.org wrote:
I've posted a comparison between Sphinx and Dexy [1] - as well as updated the phabricator ticket [2]. The tools are pretty similar in what they can produce, so it really comes down to what people are comfortable with. The learning curve for Dexy isn't steep, and I think it's just enough easier to use compared to Sphinx for our purposes.
I wasn't able to find air-tight reasoning for one over the other for qa-devel work - but found dexy a bit easier to use and template. Source for both tutorials can be found on my bitbucket profile [3].
As mike started the evaluation, the goal was to see which of the two tools would be better for qa-devel (and possibly qa) as a whole and end up with one documentation tool.
As I'm looking through the demo that he came up, adding in my own experience and what nick said about rtd.org, I'm wondering if we really need or want to have a single tool.
As I see it, both sphinx and dexy have their advantages and disadvantages. Sphinx is probably better for documenting a software project and dexy is probably better for more general documentation.
The main general advantage I see to dexy is that it makes theming and customization of output much less painful when we want to make stuff look more fedora-y. However, one of my goals for taskotron is not to restrict it to Fedora and thus, fedora branding for taskotron-specific docs is a bit of an anti-goal.
I have two reasons for wanting to keep taskotron as distro-neutral as reasonably possible:
One thing that Kamil said about a year ago now is that there are several interesting automation platforms out there but it's a shame that they're all really purpose-specific. I agree and see no reason to limit taskotron to Fedora from the start - if we can sanely make at least the core bits generic, that'll only increase the possible user/contributor base going forward.
For me, one of the overarching lessons from autoqa is that tight coupling leads to pain, lots of pain. AutoQA doesn't really work well for anything but Fedora or outside the production infrastructure. While not directly related, I do see a correlation between keeping the core bits distro agnostic and not repeating
some of the problematic parts of autoqa - it forces us to decouple some things and isolate the Fedora specific bits.
With this in mind, I propose that we use sphinx and rtd.org for taskotron and self-hosted dexy for the less structured qadevel landing page which points to various docs and resources.
Thoughts?
Tim
I think that makes sense and shouldn't be too difficult to maintain.
// Mike
qa-devel@lists.fedoraproject.org
-
Kamil Paral -
Mike Ruckman -
Nick Coghlan -
Tim Flink