You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mesos.apache.org by Benjamin Mahler <bm...@apache.org> on 2016/02/08 18:10:16 UTC
Endpoint documentation is now published!
We now have endpoint documentation published on the website:
http://mesos.apache.org/documentation/latest/endpoints/
https://issues.apache.org/jira/browse/MESOS-3831
A big thank you goes out to Kevin Klues who made this happen, thanks also
goes out to Neil Conway for making the suggestion!
Our goal here was to get the existing endpoint documentation (lives inside
the C++ source code) published on the website. So for now, the
documentation is still written within the C++ source, but we have a simple
tool to automate the generation of the markdown documentation within the
docs/ folder:
https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
Long term we're thinking it may make sense to have the help information as
markdown rather than as C++ source, but for now we at least have a way to
publish it to the users! This will encourage us to write better help
information (much of the existing help information is fairly bare).
Ben
Re: Endpoint documentation is now published!
Posted by Michael Park <mp...@apache.org>.
It looks great! Thanks Ben, Kevin, and Neil for putting this together :)
On 8 February 2016 at 23:56, Benjamin Mahler <bm...@apache.org> wrote:
> Agreed, thanks for the links.
>
> I had mentioned looking into swagger to a few folks when we started doing
> this, but we realized we needed to start small by getting the existing help
> information published.
>
> On Tue, Feb 9, 2016 at 7:25 AM, haosdent <ha...@gmail.com> wrote:
>
> > I think we could try some api generators like http://swagger.io/ or
> > https://github.com/apidoc/apidoc
> >
> > On Tue, Feb 9, 2016 at 1:10 AM, Benjamin Mahler <bm...@apache.org>
> > wrote:
> >
> >> We now have endpoint documentation published on the website:
> >>
> >> http://mesos.apache.org/documentation/latest/endpoints/
> >> https://issues.apache.org/jira/browse/MESOS-3831
> >>
> >> A big thank you goes out to Kevin Klues who made this happen, thanks
> also
> >> goes out to Neil Conway for making the suggestion!
> >>
> >> Our goal here was to get the existing endpoint documentation (lives
> inside
> >> the C++ source code) published on the website. So for now, the
> >> documentation is still written within the C++ source, but we have a
> simple
> >> tool to automate the generation of the markdown documentation within the
> >> docs/ folder:
> >>
> >>
> https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
> >>
> >> Long term we're thinking it may make sense to have the help information
> as
> >> markdown rather than as C++ source, but for now we at least have a way
> to
> >> publish it to the users! This will encourage us to write better help
> >> information (much of the existing help information is fairly bare).
> >>
> >> Ben
> >>
> >
> >
> >
> > --
> > Best Regards,
> > Haosdent Huang
> >
>
Re: Endpoint documentation is now published!
Posted by Michael Park <mp...@apache.org>.
It looks great! Thanks Ben, Kevin, and Neil for putting this together :)
On 8 February 2016 at 23:56, Benjamin Mahler <bm...@apache.org> wrote:
> Agreed, thanks for the links.
>
> I had mentioned looking into swagger to a few folks when we started doing
> this, but we realized we needed to start small by getting the existing help
> information published.
>
> On Tue, Feb 9, 2016 at 7:25 AM, haosdent <ha...@gmail.com> wrote:
>
> > I think we could try some api generators like http://swagger.io/ or
> > https://github.com/apidoc/apidoc
> >
> > On Tue, Feb 9, 2016 at 1:10 AM, Benjamin Mahler <bm...@apache.org>
> > wrote:
> >
> >> We now have endpoint documentation published on the website:
> >>
> >> http://mesos.apache.org/documentation/latest/endpoints/
> >> https://issues.apache.org/jira/browse/MESOS-3831
> >>
> >> A big thank you goes out to Kevin Klues who made this happen, thanks
> also
> >> goes out to Neil Conway for making the suggestion!
> >>
> >> Our goal here was to get the existing endpoint documentation (lives
> inside
> >> the C++ source code) published on the website. So for now, the
> >> documentation is still written within the C++ source, but we have a
> simple
> >> tool to automate the generation of the markdown documentation within the
> >> docs/ folder:
> >>
> >>
> https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
> >>
> >> Long term we're thinking it may make sense to have the help information
> as
> >> markdown rather than as C++ source, but for now we at least have a way
> to
> >> publish it to the users! This will encourage us to write better help
> >> information (much of the existing help information is fairly bare).
> >>
> >> Ben
> >>
> >
> >
> >
> > --
> > Best Regards,
> > Haosdent Huang
> >
>
Re: Endpoint documentation is now published!
Posted by Benjamin Mahler <bm...@apache.org>.
Agreed, thanks for the links.
I had mentioned looking into swagger to a few folks when we started doing
this, but we realized we needed to start small by getting the existing help
information published.
On Tue, Feb 9, 2016 at 7:25 AM, haosdent <ha...@gmail.com> wrote:
> I think we could try some api generators like http://swagger.io/ or
> https://github.com/apidoc/apidoc
>
> On Tue, Feb 9, 2016 at 1:10 AM, Benjamin Mahler <bm...@apache.org>
> wrote:
>
>> We now have endpoint documentation published on the website:
>>
>> http://mesos.apache.org/documentation/latest/endpoints/
>> https://issues.apache.org/jira/browse/MESOS-3831
>>
>> A big thank you goes out to Kevin Klues who made this happen, thanks also
>> goes out to Neil Conway for making the suggestion!
>>
>> Our goal here was to get the existing endpoint documentation (lives inside
>> the C++ source code) published on the website. So for now, the
>> documentation is still written within the C++ source, but we have a simple
>> tool to automate the generation of the markdown documentation within the
>> docs/ folder:
>>
>> https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
>>
>> Long term we're thinking it may make sense to have the help information as
>> markdown rather than as C++ source, but for now we at least have a way to
>> publish it to the users! This will encourage us to write better help
>> information (much of the existing help information is fairly bare).
>>
>> Ben
>>
>
>
>
> --
> Best Regards,
> Haosdent Huang
>
Re: Endpoint documentation is now published!
Posted by Benjamin Mahler <bm...@apache.org>.
Agreed, thanks for the links.
I had mentioned looking into swagger to a few folks when we started doing
this, but we realized we needed to start small by getting the existing help
information published.
On Tue, Feb 9, 2016 at 7:25 AM, haosdent <ha...@gmail.com> wrote:
> I think we could try some api generators like http://swagger.io/ or
> https://github.com/apidoc/apidoc
>
> On Tue, Feb 9, 2016 at 1:10 AM, Benjamin Mahler <bm...@apache.org>
> wrote:
>
>> We now have endpoint documentation published on the website:
>>
>> http://mesos.apache.org/documentation/latest/endpoints/
>> https://issues.apache.org/jira/browse/MESOS-3831
>>
>> A big thank you goes out to Kevin Klues who made this happen, thanks also
>> goes out to Neil Conway for making the suggestion!
>>
>> Our goal here was to get the existing endpoint documentation (lives inside
>> the C++ source code) published on the website. So for now, the
>> documentation is still written within the C++ source, but we have a simple
>> tool to automate the generation of the markdown documentation within the
>> docs/ folder:
>>
>> https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
>>
>> Long term we're thinking it may make sense to have the help information as
>> markdown rather than as C++ source, but for now we at least have a way to
>> publish it to the users! This will encourage us to write better help
>> information (much of the existing help information is fairly bare).
>>
>> Ben
>>
>
>
>
> --
> Best Regards,
> Haosdent Huang
>
Re: Endpoint documentation is now published!
Posted by haosdent <ha...@gmail.com>.
I think we could try some api generators like http://swagger.io/ or
https://github.com/apidoc/apidoc
On Tue, Feb 9, 2016 at 1:10 AM, Benjamin Mahler <bm...@apache.org> wrote:
> We now have endpoint documentation published on the website:
>
> http://mesos.apache.org/documentation/latest/endpoints/
> https://issues.apache.org/jira/browse/MESOS-3831
>
> A big thank you goes out to Kevin Klues who made this happen, thanks also
> goes out to Neil Conway for making the suggestion!
>
> Our goal here was to get the existing endpoint documentation (lives inside
> the C++ source code) published on the website. So for now, the
> documentation is still written within the C++ source, but we have a simple
> tool to automate the generation of the markdown documentation within the
> docs/ folder:
>
> https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
>
> Long term we're thinking it may make sense to have the help information as
> markdown rather than as C++ source, but for now we at least have a way to
> publish it to the users! This will encourage us to write better help
> information (much of the existing help information is fairly bare).
>
> Ben
>
--
Best Regards,
Haosdent Huang
Re: Endpoint documentation is now published!
Posted by haosdent <ha...@gmail.com>.
I think we could try some api generators like http://swagger.io/ or
https://github.com/apidoc/apidoc
On Tue, Feb 9, 2016 at 1:10 AM, Benjamin Mahler <bm...@apache.org> wrote:
> We now have endpoint documentation published on the website:
>
> http://mesos.apache.org/documentation/latest/endpoints/
> https://issues.apache.org/jira/browse/MESOS-3831
>
> A big thank you goes out to Kevin Klues who made this happen, thanks also
> goes out to Neil Conway for making the suggestion!
>
> Our goal here was to get the existing endpoint documentation (lives inside
> the C++ source code) published on the website. So for now, the
> documentation is still written within the C++ source, but we have a simple
> tool to automate the generation of the markdown documentation within the
> docs/ folder:
>
> https://github.com/apache/mesos/blob/master/support/generate-endpoint-help.py
>
> Long term we're thinking it may make sense to have the help information as
> markdown rather than as C++ source, but for now we at least have a way to
> publish it to the users! This will encourage us to write better help
> information (much of the existing help information is fairly bare).
>
> Ben
>
--
Best Regards,
Haosdent Huang