[zeromq-dev] Documentation Proposal

Brian Granger ellisonbg at gmail.com
Mon Jul 19 06:43:26 CEST 2010


On Mon, Jul 12, 2010 at 9:14 AM, Peter Alexander <vel.accel at gmail.com> wrote:
> Hi mato.
>
> On Mon, Jul 12, 2010 at 11:17 AM, Martin Lucina <mato at kotelna.sk> wrote:
>> Hi Peter,
>>
>> having read through this thread I have the following comments:
>>
>> 1) Re. developer documentation generated from the source with Doxygen: I
>> have no real opinion on this, other than to concur with others comments
>> that to be useful it must be generated automatically from the current Git
>> master, and that the Doxygen documentation is targeted at 0MQ developers
>> and contributors rather than end users. I don't think that the Doxygen
>> documentation needs to be included with released tarballs of 0MQ.
>>
>
> This is being done now. Github does provide a "post-recieve" hook, but
> since I also want to also host a search-able log of the irc channel, i
> can easily parse for "<CIA-17>" messages and update the doxygen
> generation to make current. For now I'll just host this stuff where it
> is and run the daemon here unless otherwise directed by you guys.
>
> Btw, I have an incomplete record of the irc log file(s), if anyone has
> a mostly complete history please let me know.
>
>> 2) Re. the state of the Wiki documentation; it would be useful if someone
>> went through the Wiki and either prominently marked as deprecated or
>> (better) just removed all the old 0MQ/1.x documentation. This has been the
>> source of some confusion from people, especially with people finding old
>> 1.x documentation via search engines.
>>
>
> Yes. My this is my intention, as well as to curry *all* information
> available to a searchable, cross-reference-able data store... what
> ever form that may take. Atm, I think I will use Sphinx for this.

I haven't followed this discussion much, but Sphinx is a great option
for documentation.

>> 3) Re. the reference documentation in Git. I don't see any reason to change
>> anything here; the documentation is in a easy to write format with a
>> powerful toolchain and is separate from the Wiki for the reason that it is
>> essential material which must be packaged with the released product.
>>
>
> I agree, asciidoc is nice; not to mention man pages need to be cli
> accessible. What I can do though, is easily translate your good work
> from the repo into the form to be used for all curried information as
> I described above.
>
>> I would like to invite more people to contribute to the reference
>> documentation in Git; patches are welcome. Also, when someone writes
>> quality introductory material suitable for a tutorial this could be
>> included as a zmqtutorial(7) document, similar to how the Git people do it
>> with gittutorial(7).
>>
>> -mato
>> _______________________________________________
>> zeromq-dev mailing list
>> zeromq-dev at lists.zeromq.org
>> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>>
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>



-- 
Brian E. Granger, Ph.D.
Assistant Professor of Physics
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu
ellisonbg at gmail.com



More information about the zeromq-dev mailing list