headers
etienne.desautels | 16 Jan 2009 21:07
Picon
Gravatar

Script to autogenerate the necessary ReST files to build automatically the docs from the code


Hi,

I start to use Sphinx for our project (http://propulseart.sat.qc.ca)
and I wish to autogenerate all the docs from the code (à la epydoc).
So I have written a script that parse the directory tree of a project/
package and create all the ReST files (with the automodule directive
in it) necessary to produce the docs from the code.

I was wondering if you think it could be a good idea to bundle a
script of this kind with Sphinx?

You can see my script here:
https://svn.sat.qc.ca/trac/miville/browser/trunk/py/docs/generate_modules.py

It's a first version but I think it could easily modify/extend to be
more generic and flexible. For example I can use optparse to add some
flags to specifiy the automodule options or add a flag to specify a
file with a list of exclusions. Maybe it could be a good idea to add a
configuration file to keep the settings, etc.

To use it you call it with the package directory as first argument.
All others arguments are path that will be excluded from the
processing.

As a matter of fact, I just added 2 proposals and 4 bug report to the
Sphinx issue tracker!

And thanks for the great work.
(Continue reading)

Permalink | Reply |
headers
Roman | 29 Jan 2009 21:27
Picon

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


On Jan 16, 10:07 pm, etienne.desaut... <at> gmail.com wrote:
> Hi,

Good evening.

> I start to use Sphinx for our project (http://propulseart.sat.qc.ca)
> and I wish to autogenerate all the docs from the code (à la epydoc).
> So I have written a script that parse the directory tree of a project/
> package and create all the ReST files (with the automodule directive
> in it) necessary to produce the docs from the code.
>
> I was wondering if you think it could be a good idea to bundle a
> script of this kind with Sphinx?

I tried your script and it did the job quite nice.

Correct me if I wrong, but this is  "one time" script - I can run it
only once. If I modify the generated files, the script will not
preserve the changes.

May be the better solution is to add  :autopackage: directive, which
has the following properrties/attributes:
* "understand" __init__.py file role
* :maxdepth:
* support merge of hand-written documentation and the one extracted
from code ( http://sphinx.pocoo.org/ext/autodoc.html?highlight=autodoc#module-sphinx.ext.autodoc
),
* include/exclude glob patterns
(Continue reading)

Permalink | Reply |
headers
Tim Michelsen | 30 Jan 2009 00:35
Picon

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


Hello fellow Sphinxers,
this is getting more and more useful.
>> I was wondering if you think it could be a good idea to bundle a
>> script of this kind with Sphinx?
> 
> I tried your script and it did the job quite nice.
> 
> Correct me if I wrong, but this is  "one time" script - I can run it
> only once. If I modify the generated files, the script will not
> preserve the changes.
Is it planned to include this into Sphinx main distribution?

> May be Sphinx should introduce :pkg: directive, which allows to refer
> to the whole package.
A very good idea. May you file a feature request?

Regards,
Timmie

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Permalink | Reply |
headers
etienned | 2 Feb 2009 16:46
Picon
Gravatar

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


 <at> Timmie

> Here are my improvement suggestions:

> * specify any input path => currently works only with
>   generate_modules.py .

Oups! I didn't test other scenarios. I should fix this.

> * specify a different output path for the generated files

Good idea. Like I said in my post, I think this script really need an
optparse addition to easily add all this kind of configuration flags.

 <at> Roman

> Correct me if I wrong, but this is  "one time" script - I can run it
> only once. If I modify the generated files, the script will not
> preserve the changes.

Right now, before creating each ReST file, the script check if the
ReST file already exist and in such case doesn't recreate it. This
way, if you modify some of the generated files, you can keep them
untoutch when you re-run the script. If you want to regenerate some
files you need to delete them before running the script again (I was
thinking of adding a --force flag to force the regenerating of all
files without deleting them before.). I choose this way because it was
really simple to implement and to use. I know it's not powerful enough
for all the scenarios but it's better then nothing.
(Continue reading)

Permalink | Reply |
headers
Tim Michelsen | 3 Feb 2009 19:50
Picon

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


Hello,
just for interest:

I added a inclusion request to Sphinx bitbucket at:
http://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx

Regards,
Timmie

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Permalink | Reply |
headers
etienned | 7 Feb 2009 02:02
Picon
Gravatar

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


> I added a inclusion request to Sphinx bitbucket at:http://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-...

Thanks

I would like to add that I received an enhance version of the script
from Dennis Muhlestein in our bug tracker (thanks!) that add optparse
with some command line options for configuring the destination
directory, the doc header and the file suffix.

I took his version, corrected 2 bugs (one cosmetic, the other one was
about the working path) and add 4 more command line options:
 # maxdepth
 # dry-run
 # force
 # no-toc

So take a look if your interested.

Etienne

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Permalink | Reply |
headers
Georg Brandl | 22 Jan 2009 20:20
Favicon
Gravatar

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


etienne.desautels <at> gmail.com schrieb:
> Hi,
> 
> I start to use Sphinx for our project (http://propulseart.sat.qc.ca)
> and I wish to autogenerate all the docs from the code (à la epydoc).
> So I have written a script that parse the directory tree of a project/
> package and create all the ReST files (with the automodule directive
> in it) necessary to produce the docs from the code.
> 
> I was wondering if you think it could be a good idea to bundle a
> script of this kind with Sphinx?
> 
> You can see my script here:
> https://svn.sat.qc.ca/trac/miville/browser/trunk/py/docs/generate_modules.py
> 
> It's a first version but I think it could easily modify/extend to be
> more generic and flexible. For example I can use optparse to add some
> flags to specifiy the automodule options or add a flag to specify a
> file with a list of exclusions. Maybe it could be a good idea to add a
> configuration file to keep the settings, etc.
> 
> To use it you call it with the package directory as first argument.
> All others arguments are path that will be excluded from the
> processing.

Thanks for the pointer to your script! I will think about it, together
with numpy's autosummary, for the next Sphinx version.

> As a matter of fact, I just added 2 proposals and 4 bug report to the
(Continue reading)

Permalink | Reply |
headers
Timmie | 28 Jan 2009 14:26
Picon

Re: Script to autogenerate the necessary ReST files to build automatically the docs from the code


Hello,
I tried the script out and think it is really useful.

I would opt to include it into Sphinx.

Here are my improvement suggestions:

* specify any input path => currently works only with
  generate_modules.py .

* specify a different output path for the generated files

Kind regards,
Timmie

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-dev <at> googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+unsubscribe <at> googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Permalink | Reply |

Gmane