Docs and the :manpage: tag

[Nicola Nye]

Hi Nic,

So it turns out that the regex I inherited from the other code wasn't
escaping the hyphen properly, so that particular instance didn't like
cyrus-master(8).

And then in the interests of completeness, I tried doing the
manpage/cyrusman substitution for myself, and we appear to have some
references to :manpage:`cyradmin(1p)` in cyr_expire. So I've catered for
that too now.

New stuff all shiny and committed.

Our use of section 8 vs section 1 seems a bit inconsistent. For the
moment the cyrusman role just looks for all section 8 and section 1
stuff in the same "commands" directory. Should they actually be split
apart into separate directories? What does the generated man page layout
look like? Ideally our html should match.

Time to feed the kids fish and chips before I go frolicking off for some
tasty tapas.

Nicola


On Fri, Aug 14, 2015, at 01:19 PM, Nic Bernstein wrote:
> Nicola,
>
    Well, still not working for me.  Is it working for you?
>
>
    Here's what I get after performing a "git pull":
>
>> nic at flatboy:~/Checkouts/cyrus.foundation/cyrus-docs$ for file in
>> `grep -lR ":manpage:" source/imap`; do sed -i $file -e
>> 's/:manpage:/:cyrusman:/g'; done nic at flatboy:~/Checkouts/cyrus.foundation/cyrus-
>> docs$make man html
sphinx-build -b cyrman -d build/doctrees   source build/man Running
Sphinx v1.2.2 Initializing cyrusman plugin loading pickled
environment... not yet created building [cyrman]: all manpages updating
environment: 274 added, 0 changed, 0 removed
reading sources... [  6%] imap/admin/commands/ctl_conversationsdb
:cyrusman: error: imap/admin/commands/ctl_conversationsdb: 159: Missing
man page section for 'cyrus-master(8)'. make: *** [man] Error 1
>>
> It struck me as odd that the error message, about no man page
    section, itself included a man page section.  Upon checking, I see
    this:
>
>> See Also
========
:cyrusman:`imapd.conf(5)`, :cyrusman:`cyrus-master(8)`
>>
> So I think whatever check your cyrusman 'role' is performing has a
    problem.
>
>
    It's too late in the evening, being 3-scotch o'clock, for me to
    diagnose this from this side of the world. ;-0
>
    -nic
>
>
> On 08/13/2015 09:25 PM, Nicola Nye
      wrote:
>> Hi Nic,
>>
>> There were a bunch of :manpage: references that were missing
        the (x) section number. I've amended the pages and committed a
        new version of the code which provides better reporting.
>>
>> Do you know if there's any :manpage: references that are
        referencing non-cyrus content? (We don't want to :cyrusman:ls
        for instance)
>>
>> Let me know if this works any better for you!
>>
>> On Fri, Aug 14, 2015, at 01:00 AM, Nic Bernstein wrote:
>>> On 08/13/2015 12:15 AM, Nicola Nye wrote:
>>>
>>>> Delicious victory is mine!
>>>>
>>>> We now have a :cyrusman: sphinx option which generates
            urls into our docs.cyrus.foundation tree, performing string
            munging magic to match the generated url to our directory
            and filename structure.
>>>>
>>>> Now, to look at updating all the references in our
            existing docs so that it uses the new tag...
>>>>
>>>
>>> Nicola, Doesn't work for me.
>>>
>>> I pulled your changes, and then ran the following script to
          replace all :manpage: references with :cyrusman:
>>>
>>>> $ for file in `grep -lR ":manpage:" source/imap`; do sed -i $file
>>>> -e 's/:manpage:/:cyrusman:/g'; done

>>>>
>>> Then I ran a build:
>>>
>>>> $ make man html
sphinx-build -b cyrman -d build/doctrees   source build/man Running
Sphinx v1.2.2 Initializing cyrusman plugin loading pickled
environment... done building [cyrman]: all manpages updating
environment: [extensions changed] 274 added, 18 changed, 0 removed
reading sources... [  3%] imap/admin/access-control/rights-reference
>>>> Exception occurred:
  File "/home/nic/Checkouts/cyrus.foundation/cyrus-
  docs/source/exts/sphinxlocal/writers/cyrusman.py", line 49, in
  man_role  manpage_num = m.group(2) AttributeError: 'NoneType' object
  has no attribute 'group'
>>>> The full traceback has been saved in /tmp/sphinx-err-yWaXf3.log, if
>>>> you want to report the issue to the developers.
>>> Full traceback is attached.
>>>
>>> Cheers, -nic
>>>
>>> --
Nic Bernstein                             nic at onlight.com Onlight llc.
www.onlight.com219 N. Milwaukee St., Ste. 2A            v. 414.272.4477
Milwaukee, Wisconsin  53202               f. 414.290.0335

>>>
>>> Email had 1 attachment:


>>>  * sphinx-err-yWaXf3.log  8k (text/x-log)
>>
>
> --
Nic Bernstein                             nic at onlight.com Onlight Inc.
www.onlight.com6525 W Bluemound Rd., Ste 24             v. 414.272.4477
Milwaukee, Wisconsin  53213-4073          f. 414.290.0335
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150814/a96b3783/attachment.html