regenerating man pages

regenerating man pages

[Ken Dreyer]

I had a question about the way that we're handling man pages.

In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate rbd(8)
man page", it looks like man/rbd.8 was regenerated from doc/man/8/rbd.rst

It seems like it would be more efficient to avoid storing man pages in
Git and generate them dynamically at build time instead?

https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt

"admin/build-doc" does a lot of things (including man page generation).
Could we simply run the "sphinx-build -b man" part at build time as a
part of "make"?

Just trying to understand what's intentional, whether I'm missing
something, etc.

- Ken

Re: regenerating man pages

[Josh Durgin]

On 03/17/2015 09:40 AM, Ken Dreyer wrote:
> I had a question about the way that we're handling man pages.
>
> In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate rbd(8)
> man page", it looks like man/rbd.8 was regenerated from doc/man/8/rbd.rst
>
> It seems like it would be more efficient to avoid storing man pages in
> Git and generate them dynamically at build time instead?

Yes, that'd be great!

> https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
>
> "admin/build-doc" does a lot of things (including man page generation).
> Could we simply run the "sphinx-build -b man" part at build time as a
> part of "make"?

I don't see a reason not to. It's just a matter of making it work on all
the platforms we're building packages for. That might be annoying for
the entirety of build-doc, but for just building man pages it should
be simple.

Josh

Re: regenerating man pages

[Sage Weil]

On Tue, 17 Mar 2015, Josh Durgin wrote:
> On 03/17/2015 09:40 AM, Ken Dreyer wrote:
> > I had a question about the way that we're handling man pages.
> > 
> > In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate rbd(8)
> > man page", it looks like man/rbd.8 was regenerated from doc/man/8/rbd.rst
> > 
> > It seems like it would be more efficient to avoid storing man pages in
> > Git and generate them dynamically at build time instead?
> 
> Yes, that'd be great!
> 
> > https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
> > 
> > "admin/build-doc" does a lot of things (including man page generation).
> > Could we simply run the "sphinx-build -b man" part at build time as a
> > part of "make"?
> 
> I don't see a reason not to. It's just a matter of making it work on all
> the platforms we're building packages for. That might be annoying for
> the entirety of build-doc, but for just building man pages it should
> be simple.

I think the original reason we didn't was just because there are a lot of 
dependencies for building the docs, so this inflates Build-Depends.  That 
doesn't particularly bother me, though, if the deps do in fact exist.

sage

Re: regenerating man pages

[David Zafman]

I found that I could not build the docs on Ubuntu 14.10 with the proper 
packages installed.  Kefu is looking into Asphyxiate which is very 
tempermental.  I installed an Ubuntu 11.10 in order to generate docs.

David

On 3/17/15 10:11 AM, Sage Weil wrote:
> On Tue, 17 Mar 2015, Josh Durgin wrote:
>> On 03/17/2015 09:40 AM, Ken Dreyer wrote:
>>> I had a question about the way that we're handling man pages.
>>>
>>> In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate rbd(8)
>>> man page", it looks like man/rbd.8 was regenerated from doc/man/8/rbd.rst
>>>
>>> It seems like it would be more efficient to avoid storing man pages in
>>> Git and generate them dynamically at build time instead?
>> Yes, that'd be great!
>>
>>> https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
>>>
>>> "admin/build-doc" does a lot of things (including man page generation).
>>> Could we simply run the "sphinx-build -b man" part at build time as a
>>> part of "make"?
>> I don't see a reason not to. It's just a matter of making it work on all
>> the platforms we're building packages for. That might be annoying for
>> the entirety of build-doc, but for just building man pages it should
>> be simple.
> I think the original reason we didn't was just because there are a lot of
> dependencies for building the docs, so this inflates Build-Depends.  That
> doesn't particularly bother me, though, if the deps do in fact exist.
>
> sage
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: regenerating man pages

[Gregory Farnum]

Yeah. If this has gotten easier it's fine, but asphyxiate required a
*lot* of tooling that I'd rather we not require as developer build
deps. I'd imagine we can just produce them as part of the Jenkins
build procedure or something?
-Greg

On Tue, Mar 17, 2015 at 12:27 PM, David Zafman <dzafman@redhat.com> wrote:
>
> I found that I could not build the docs on Ubuntu 14.10 with the proper
> packages installed.  Kefu is looking into Asphyxiate which is very
> tempermental.  I installed an Ubuntu 11.10 in order to generate docs.
>
> David
>
>
> On 3/17/15 10:11 AM, Sage Weil wrote:
>>
>> On Tue, 17 Mar 2015, Josh Durgin wrote:
>>>
>>> On 03/17/2015 09:40 AM, Ken Dreyer wrote:
>>>>
>>>> I had a question about the way that we're handling man pages.
>>>>
>>>> In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate rbd(8)
>>>> man page", it looks like man/rbd.8 was regenerated from
>>>> doc/man/8/rbd.rst
>>>>
>>>> It seems like it would be more efficient to avoid storing man pages in
>>>> Git and generate them dynamically at build time instead?
>>>
>>> Yes, that'd be great!
>>>
>>>> https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
>>>>
>>>> "admin/build-doc" does a lot of things (including man page generation).
>>>> Could we simply run the "sphinx-build -b man" part at build time as a
>>>> part of "make"?
>>>
>>> I don't see a reason not to. It's just a matter of making it work on all
>>> the platforms we're building packages for. That might be annoying for
>>> the entirety of build-doc, but for just building man pages it should
>>> be simple.
>>
>> I think the original reason we didn't was just because there are a lot of
>> dependencies for building the docs, so this inflates Build-Depends.  That
>> doesn't particularly bother me, though, if the deps do in fact exist.
>>
>> sage
>> --
>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: regenerating man pages

[Josh Durgin]

On 03/17/2015 12:32 PM, Gregory Farnum wrote:
> Yeah. If this has gotten easier it's fine, but asphyxiate required a
> *lot* of tooling that I'd rather we not require as developer build
> deps. I'd imagine we can just produce them as part of the Jenkins
> build procedure or something?

None of that is needed for man pages or developer builds. asphyxiate is
just for getting doxygen into the docs. The man pages are generated with
plain sphinx, and do not need to be part of developer builds. Only
package builds need to generate them.

Josh

> On Tue, Mar 17, 2015 at 12:27 PM, David Zafman <dzafman@redhat.com> wrote:
>>
>> I found that I could not build the docs on Ubuntu 14.10 with the proper
>> packages installed.  Kefu is looking into Asphyxiate which is very
>> tempermental.  I installed an Ubuntu 11.10 in order to generate docs.
>>
>> David
>>
>>
>> On 3/17/15 10:11 AM, Sage Weil wrote:
>>>
>>> On Tue, 17 Mar 2015, Josh Durgin wrote:
>>>>
>>>> On 03/17/2015 09:40 AM, Ken Dreyer wrote:
>>>>>
>>>>> I had a question about the way that we're handling man pages.
>>>>>
>>>>> In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate rbd(8)
>>>>> man page", it looks like man/rbd.8 was regenerated from
>>>>> doc/man/8/rbd.rst
>>>>>
>>>>> It seems like it would be more efficient to avoid storing man pages in
>>>>> Git and generate them dynamically at build time instead?
>>>>
>>>> Yes, that'd be great!
>>>>
>>>>> https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
>>>>>
>>>>> "admin/build-doc" does a lot of things (including man page generation).
>>>>> Could we simply run the "sphinx-build -b man" part at build time as a
>>>>> part of "make"?
>>>>
>>>> I don't see a reason not to. It's just a matter of making it work on all
>>>> the platforms we're building packages for. That might be annoying for
>>>> the entirety of build-doc, but for just building man pages it should
>>>> be simple.
>>>
>>> I think the original reason we didn't was just because there are a lot of
>>> dependencies for building the docs, so this inflates Build-Depends.  That
>>> doesn't particularly bother me, though, if the deps do in fact exist.
>>>
>>> sage
>>> --
>>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>>> the body of a message to majordomo@vger.kernel.org
>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
>>
>> --
>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: regenerating man pages

[Sage Weil]

On Tue, 17 Mar 2015, Josh Durgin wrote:
> On 03/17/2015 12:32 PM, Gregory Farnum wrote:
> > Yeah. If this has gotten easier it's fine, but asphyxiate required a
> > *lot* of tooling that I'd rather we not require as developer build
> > deps. I'd imagine we can just produce them as part of the Jenkins
> > build procedure or something?
> 
> None of that is needed for man pages or developer builds. asphyxiate is
> just for getting doxygen into the docs. The man pages are generated with
> plain sphinx, and do not need to be part of developer builds. Only
> package builds need to generate them.

Note that in practice devs will run install-deps.sh, which greps the 
Build-depends out of the spec or debian/control file, so they'll probably 
end up installing sphinx.  If it's just that I don't think it'll cause 
problems though!

sage

> 
> Josh
> 
> > On Tue, Mar 17, 2015 at 12:27 PM, David Zafman <dzafman@redhat.com> wrote:
> > > 
> > > I found that I could not build the docs on Ubuntu 14.10 with the proper
> > > packages installed.  Kefu is looking into Asphyxiate which is very
> > > tempermental.  I installed an Ubuntu 11.10 in order to generate docs.
> > > 
> > > David
> > > 
> > > 
> > > On 3/17/15 10:11 AM, Sage Weil wrote:
> > > > 
> > > > On Tue, 17 Mar 2015, Josh Durgin wrote:
> > > > > 
> > > > > On 03/17/2015 09:40 AM, Ken Dreyer wrote:
> > > > > > 
> > > > > > I had a question about the way that we're handling man pages.
> > > > > > 
> > > > > > In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate
> > > > > > rbd(8)
> > > > > > man page", it looks like man/rbd.8 was regenerated from
> > > > > > doc/man/8/rbd.rst
> > > > > > 
> > > > > > It seems like it would be more efficient to avoid storing man pages
> > > > > > in
> > > > > > Git and generate them dynamically at build time instead?
> > > > > 
> > > > > Yes, that'd be great!
> > > > > 
> > > > > > https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
> > > > > > 
> > > > > > "admin/build-doc" does a lot of things (including man page
> > > > > > generation).
> > > > > > Could we simply run the "sphinx-build -b man" part at build time as
> > > > > > a
> > > > > > part of "make"?
> > > > > 
> > > > > I don't see a reason not to. It's just a matter of making it work on
> > > > > all
> > > > > the platforms we're building packages for. That might be annoying for
> > > > > the entirety of build-doc, but for just building man pages it should
> > > > > be simple.
> > > > 
> > > > I think the original reason we didn't was just because there are a lot
> > > > of
> > > > dependencies for building the docs, so this inflates Build-Depends.
> > > > That
> > > > doesn't particularly bother me, though, if the deps do in fact exist.
> > > > 
> > > > sage
> > > > --
> > > > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > > > the body of a message to majordomo@vger.kernel.org
> > > > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > > 
> > > 
> > > --
> > > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > > the body of a message to majordomo@vger.kernel.org
> > > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > --
> > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> 

Re: regenerating man pages

[kefu chai]

sorry for resending this mail. i sent it using multipart encoding and
got rejected by the mail server.

On Wed, 18 Mar 2015 at 03:47 Sage Weil <sweil@redhat.com> wrote:
>
> On Tue, 17 Mar 2015, Josh Durgin wrote:
> > On 03/17/2015 12:32 PM, Gregory Farnum wrote:
> > > Yeah. If this has gotten easier it's fine, but asphyxiate required a
> > > *lot* of tooling that I'd rather we not require as developer build
> > > deps. I'd imagine we can just produce them as part of the Jenkins
> > > build procedure or something?
> >
> > None of that is needed for man pages or developer builds. asphyxiate is
> > just for getting doxygen into the docs. The man pages are generated with
> > plain sphinx, and do not need to be part of developer builds. Only
> > package builds need to generate them.
>
> Note that in practice devs will run install-deps.sh, which greps the
> Build-depends out of the spec or debian/control file, so they'll probably
> end up installing sphinx.  If it's just that I don't think it'll cause
> problems though!


i failed to find sphinx in ceph.spec.in or debian/control. so we might
want to add it? if we expect the packager to generate the man pages,
maybe we should put it into the Build-Depends. and blacklist it in the
install-deps.sh?

>
>
> sage
>
> >
> > Josh
> >
> > > On Tue, Mar 17, 2015 at 12:27 PM, David Zafman <dzafman@redhat.com> wrote:
> > > >
> > > > I found that I could not build the docs on Ubuntu 14.10 with the proper
> > > > packages installed.  Kefu is looking into Asphyxiate which is very
> > > > tempermental.  I installed an Ubuntu 11.10 in order to generate docs.
> > > >
> > > > David
> > > >
> > > >
> > > > On 3/17/15 10:11 AM, Sage Weil wrote:
> > > > >
> > > > > On Tue, 17 Mar 2015, Josh Durgin wrote:
> > > > > >
> > > > > > On 03/17/2015 09:40 AM, Ken Dreyer wrote:
> > > > > > >
> > > > > > > I had a question about the way that we're handling man pages.
> > > > > > >
> > > > > > > In 356a749f63181d401d16371446bb8dc4f196c2a6 , "rbd: regenerate
> > > > > > > rbd(8)
> > > > > > > man page", it looks like man/rbd.8 was regenerated from
> > > > > > > doc/man/8/rbd.rst
> > > > > > >
> > > > > > > It seems like it would be more efficient to avoid storing man pages
> > > > > > > in
> > > > > > > Git and generate them dynamically at build time instead?
> > > > > >
> > > > > > Yes, that'd be great!
> > > > > >
> > > > > > > https://github.com/ceph/ceph/blob/master/admin/manpage-howto.txt
> > > > > > >
> > > > > > > "admin/build-doc" does a lot of things (including man page
> > > > > > > generation).
> > > > > > > Could we simply run the "sphinx-build -b man" part at build time as
> > > > > > > a
> > > > > > > part of "make"?
> > > > > >
> > > > > > I don't see a reason not to. It's just a matter of making it work on
> > > > > > all
> > > > > > the platforms we're building packages for. That might be annoying for
> > > > > > the entirety of build-doc, but for just building man pages it should
> > > > > > be simple.
> > > > >
> > > > > I think the original reason we didn't was just because there are a lot
> > > > > of
> > > > > dependencies for building the docs, so this inflates Build-Depends.
> > > > > That
> > > > > doesn't particularly bother me, though, if the deps do in fact exist.


yeah. to move the generated artifacts out of the git repo, and to
maintain man pages, probably we can

1. extract the man page rendering out of build-doc,
2. and make it a configurable option in configure.ac. so developer
builds are not impacted.
3. enable it in the ceph.spec.in and debian/rules, so the packager
won't miss the man pages.

if we are good with this proposal, i will send a PR later on.

for embedding doxygen docs in sphinx, and avoiding extra maintenance
overhead to dodge the unsupported sections issues (e.g.
https://github.com/ceph/asphyxiate/issues)  :

1. let's switch to breathe (see the discussion in
https://github.com/ceph/asphyxiate/pull/2). i checked the generated
doc at rados/api/librados/index.html, it looks good.
2. et voilà !

i am sending a pull request for the breathe changes:
https://github.com/ceph/ceph/pull/4058 .

>
> > > > >
> > > > > sage
> > > > > --
> > > > > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > > > > the body of a message to majordomo@vger.kernel.org
> > > > > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > > >
> > > >
> > > > --
> > > > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > > > the body of a message to majordomo@vger.kernel.org
> > > > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > > --
> > > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > > the body of a message to majordomo@vger.kernel.org
> > > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > >
> >
> > --
> > To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> >
> >
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html




-- 
Regards
Kefu Chai
--
To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html