[tryton-debian] Packaging of suds-jurko (was: suds)

Fri Jul 4 11:09:55 UTC 2014

* Jurko Gospodnetić: " Re: Packaging of suds-jurko (was: suds)" (Thu, 03 Jul
  2014 11:32:28 +0200):

Hi Jurko,

> On 3.7.2014. 0:07, Mathias Behrle wrote:
> >> My epydocs experience is *very* rusty.  How hard would it be to covert the
> >> docs to Sphinx-consumable reST?  Clearly, that's the state of the art in
> >> Python documentation these days.
> >
> > That was my initial thought, too. But then I supposed, that Jurko probably
> > wanted to remain as near to the origin as possible in case his project
> > would be re-merged. But at a second glance I think, that the migration of
> > docs could also merged back as an improvement.
> >
> > Any thoughts, Jurko?
> 
>    I personally have no experience with epydoc and only some slight 
> experience with Sphinx, and don't really care one way or the other at 
> this point which one gets used. Since Sphinx is the de-facto standard 
> today - I'd like to port the docs to Sphinx, but that can happen at a 
> later time as well.

Completely agreed.

>    A plan that sounds reasonable to me:
> 
> Phase 1.
>    - get the current docs building as they stand now - whatever takes 
> the least effort
>    - doc sources & infrastructure stored in the project's main version 
> control repository
>    - a build system that can generate the docs in html/pdf/txt/whatever 
> format
> 
> Phase 2.
>    - generated release docs included in the published distributions, 
> e.g. uploaded together with the release packages onto PyPI & BitBucket
>    - find out where the original suds project docs are kept, e.g. wiki 
> at fedorahosted.org, generated code-level docs at 
> http://jortel.fedorapeople.org/suds/doc
>    - a distribution system that can keep an up-to-date version readily 
> available in a public location, e.g. on https://readthedocs.org or the 
> same site where the original project is hosted, possibly replacing the 
> original project's docs
> 
> Phase 3.
>    - port the docs to Sphinx
> 
>    Since the original project already has publicly available docs, I'd 
> be fine with replacing the original suds project after phase 2.
> 
>    If later phases are something that can be integrated 'at no cost' 
> into earlier ones, I'm all for it, but I don't see it as a strict 
> requirement.
> 
> Some more thoughts on the scheduling:
>    - phase 1 should not take much time, assuming the original project 
> did have that automated somehow
>    - if the original project had only a manually maintained WIKI as its 
> basic docs - I'll have to see what to do about that as I really would 
> not like a separate project setup like that
>    - phase 2 might be tricky - I think readthedocs.org does not work 
> with epydoc, but only sphinx so unless we manage to take over the 
> original project's hosting locations it might be necessary to go the 
> sphinx route earlier - essentially - more research is required :-)
>    - as for phase 3 - the original project's autogenerated API docs 
> would need to me transformed so they are generated using some sphinx plugin
>    - suds does not have a terribly huge code-base so I guess any source 
> code formatting/markup changes can be done in a full day or two
> 
>    I can do the legwork, go through the docs and update as needed but 
> I'd rather not have such a potentially long-lasting task be a 
> requirement for something with a deadline and constantly have that on my 
> conscience. My day-job can easily take me away from suds for weeks at a 
> time. :-)
> 
>    And I really really really would not like to have to go through all 
> the docstrings and update their markup more than once. :-)

My personal approach after a short glance to the existing documentation would
be:

- Release now after renaming the project without the docs (the existing
  documentation of suds is still existing on the web and should be roughly
  enough at this very moment).
- Convert the available docs immediately to Sphinx, which AFAIS would mean
  - Get the wiki page from the fedora wiki [1], which is in mediawiki format,
    give it some love and convert it to sphinx. I attached the export of this
    page to this mail.
  - Convert the docstrings to Sphinx format
    - Here I found most interesting this sed script [2].
  - or alternatively use a translation mechanism of Sphinx to use the current
    docstrings [3].
- Add the documentation, when ready, to the project and publish on
  read-the-docs.

Personally I would prefer to convert at once and to not invest time in work,
that will be superseeded anyway. This sequence of steps seems to me the most
effective way to get things done.

HTH,
Mathias

[1] https://fedorahosted.org/suds/wiki/Documentation
[2]
http://www.tomaz.me/2013/09/28/migrating-from-epydoc-to-sphinx-style-docstrings-using-sed-and-some-command-line-fu.html
[3]
http://stackoverflow.com/questions/10012741/automated-way-to-switch-from-epydocs-docstring-formatting-to-sphinx-docstring-f

-- 

    Mathias Behrle
    PGP/GnuPG key availabable from any keyserver, ID: 0x8405BBF6
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: suds_wiki_documentation.txt
URL: <http://lists.alioth.debian.org/pipermail/tryton-debian/attachments/20140704/4d1e247f/attachment-0001.txt>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/tryton-debian/attachments/20140704/4d1e247f/attachment-0001.sig>