Docs and the :manpage: tag

[Nic Bernstein]

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 Bernsteinnic at onlight.com  <mailto:nic at onlight.com>
>> Onlight llc.www.onlight.com  <http://www.onlight.com>219 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.com
6525 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/20150813/0314dc4a/attachment-0001.html