You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mesos.apache.org by James Peach <jo...@gmail.com> on 2015/10/03 00:51:13 UTC
RFC convert documentation to Sphinx
Hi all,
I'd like to discuss using Sphinx (http://sphinx-doc.org) for the Mesos documentation.
Pros:
- you can generate HTML docs, PDF, single-page HTML
- you can generate man-pages for the user commands
- there's more markup
- supports indexing, cross-referencing and simple searching
- you can your own markup for cross-referencing and formatting
- it is easy to publish multiple version on readthedocs.org
Cons:
- not sure how the website integration would work
- there's more markup (more docs syntax to learn)
If there's interest (and a shepherd), then I'm willing to do the conversion.
cheers,
James
Re: RFC convert documentation to Sphinx
Posted by Alexander Rojas <al...@mesosphere.io>.
I would vote -1. There’s some cost associated with having to learn yet another documentation syntax, while almost all the tools we use easily support markdown. This feels a little like asking to use mercurial instead of git, sure it might be better at some stuff, but we will definitely find problems at some point, and honestly, when you check the amount of tools available, you have the feeling that md already won.
> On 03 Oct 2015, at 00:51, James Peach <jo...@gmail.com> wrote:
>
> Hi all,
>
> I'd like to discuss using Sphinx (http://sphinx-doc.org) for the Mesos documentation.
>
> Pros:
> - you can generate HTML docs, PDF, single-page HTML
> - you can generate man-pages for the user commands
> - there's more markup
> - supports indexing, cross-referencing and simple searching
> - you can your own markup for cross-referencing and formatting
> - it is easy to publish multiple version on readthedocs.org
>
> Cons:
> - not sure how the website integration would work
> - there's more markup (more docs syntax to learn)
>
> If there's interest (and a shepherd), then I'm willing to do the conversion.
>
> cheers,
> James
Re: RFC convert documentation to Sphinx
Posted by James Peach <jo...@gmail.com>.
> On Oct 4, 2015, at 5:23 PM, Marco Massenzio <ma...@mesosphere.io> wrote:
>
> +1 for Sphinx
> (and RST - *way* better than MD :)
>
> To do the autoconversion, I've used pandoc [0] in the past and (at least
> for me) it worked just fine.
>
> @James - if you do go ahead with the conversion, feel free to ping me for
> helping out!
Ok, I filed https://issues.apache.org/jira/browse/MESOS-3598. I'll try to take a crack at a proof-of-concept next week.
cheers,
James
Re: RFC convert documentation to Sphinx
Posted by Marco Massenzio <ma...@mesosphere.io>.
+1 for Sphinx
(and RST - *way* better than MD :)
To do the autoconversion, I've used pandoc [0] in the past and (at least
for me) it worked just fine.
@James - if you do go ahead with the conversion, feel free to ping me for
helping out!
[0] http://pandoc.org/
*Marco Massenzio*
*Distributed Systems Engineerhttp://codetrips.com <http://codetrips.com>*
On Sat, Oct 3, 2015 at 12:36 AM, haosdent <ha...@gmail.com> wrote:
> Sphinx requires rst format. If we want to use it, I think have to use some
> tools to convert markdown to rst when generate Sphinx documents.
>
> Actually, I deploy mesos documents in readthedocs before.
> http://mesos.readthedocs.org/en/0.24.1/getting-started/ In that website,
> you could search and swtich to different versions, also could download pdf
> or epub.
>
> On Sat, Oct 3, 2015 at 9:58 AM, suraj acharya <su...@gmail.com> wrote:
>
> > I am a new guy and I can help on this project.
> >
> > Suraj
> >
> > -Suraj Acharya
> >
> > On Fri, Oct 2, 2015 at 5:51 PM, James Peach <jo...@gmail.com> wrote:
> >
> > > Hi all,
> > >
> > > I'd like to discuss using Sphinx (http://sphinx-doc.org) for the Mesos
> > > documentation.
> > >
> > > Pros:
> > > - you can generate HTML docs, PDF, single-page HTML
> > > - you can generate man-pages for the user commands
> > > - there's more markup
> > > - supports indexing, cross-referencing and simple searching
> > > - you can your own markup for cross-referencing and formatting
> > > - it is easy to publish multiple version on readthedocs.org
> > >
> > > Cons:
> > > - not sure how the website integration would work
> > > - there's more markup (more docs syntax to learn)
> > >
> > > If there's interest (and a shepherd), then I'm willing to do the
> > > conversion.
> > >
> > > cheers,
> > > James
> >
>
>
>
> --
> Best Regards,
> Haosdent Huang
>
Re: RFC convert documentation to Sphinx
Posted by haosdent <ha...@gmail.com>.
Sphinx requires rst format. If we want to use it, I think have to use some
tools to convert markdown to rst when generate Sphinx documents.
Actually, I deploy mesos documents in readthedocs before.
http://mesos.readthedocs.org/en/0.24.1/getting-started/ In that website,
you could search and swtich to different versions, also could download pdf
or epub.
On Sat, Oct 3, 2015 at 9:58 AM, suraj acharya <su...@gmail.com> wrote:
> I am a new guy and I can help on this project.
>
> Suraj
>
> -Suraj Acharya
>
> On Fri, Oct 2, 2015 at 5:51 PM, James Peach <jo...@gmail.com> wrote:
>
> > Hi all,
> >
> > I'd like to discuss using Sphinx (http://sphinx-doc.org) for the Mesos
> > documentation.
> >
> > Pros:
> > - you can generate HTML docs, PDF, single-page HTML
> > - you can generate man-pages for the user commands
> > - there's more markup
> > - supports indexing, cross-referencing and simple searching
> > - you can your own markup for cross-referencing and formatting
> > - it is easy to publish multiple version on readthedocs.org
> >
> > Cons:
> > - not sure how the website integration would work
> > - there's more markup (more docs syntax to learn)
> >
> > If there's interest (and a shepherd), then I'm willing to do the
> > conversion.
> >
> > cheers,
> > James
>
--
Best Regards,
Haosdent Huang
Re: RFC convert documentation to Sphinx
Posted by suraj acharya <su...@gmail.com>.
I am a new guy and I can help on this project.
Suraj
-Suraj Acharya
On Fri, Oct 2, 2015 at 5:51 PM, James Peach <jo...@gmail.com> wrote:
> Hi all,
>
> I'd like to discuss using Sphinx (http://sphinx-doc.org) for the Mesos
> documentation.
>
> Pros:
> - you can generate HTML docs, PDF, single-page HTML
> - you can generate man-pages for the user commands
> - there's more markup
> - supports indexing, cross-referencing and simple searching
> - you can your own markup for cross-referencing and formatting
> - it is easy to publish multiple version on readthedocs.org
>
> Cons:
> - not sure how the website integration would work
> - there's more markup (more docs syntax to learn)
>
> If there's interest (and a shepherd), then I'm willing to do the
> conversion.
>
> cheers,
> James