Dear Sphinx developers,
I'm a great fan of the framework and would like to contribute.
Documentation
-
Unfortunately my first problem point is, that in the documentation of the
project there is no real documentation on how to contribute. So I simply
decided to send my ideas on that way and hopefully get into discussion. On
one page it was suggested to send an email to the group, which is
impossible as a non member.
Another point is, that the interface for changing the plotting of class
documentation is not enough documented. I still don't know where and how to
change it. Since I am having up to 10 parameters in the init function of a
class and up to 10 classes in one module, the normal highlighting of the
class documentation headline is insufficient.
TODO extension bug
-
The easier point is, that there is a bug or conflict between autosummary
and the `todo` extension.
In some of my docstrings, I was beginning with::
.. todo:: To document!!
This makes the whole compiling process crash, with a useless error message.
I tried to catch this error and give a better warning. I'm pretty sure the
format I used is wrong, but at least you will get the idea. The relevant
change is at line 127::
try:
newnode['refuri'] = app.builder.get_relative_uri(
fromdocname, todo_info['docname'])
newnode['refuri'] += '#' + todo_info['target']['refid']
except NoUri:
# ignore if no URI can be determined, e.g. for LaTeX output
pass
+except:
+print Wrong todo entry:
+for key in todo_info.keys():
+print key,' : ',todo_info[key]
newnode.append(innernode)
para += newnode
My error log file is also attached. Autosummary seems to produce no 'refid'
entry but an 'id' entry with different syntax.
autodoc file generation for each module!
---
The most important change I made, and which I would like to have integrated
in the official software is to the autodoc.py. When the software is
generating rst-files automatically all modules of one package get one rst
file and so in my use case only one web page, which is nearly unreadable.
So I added the option to generate one file for each module and only have an
auto-summary of the modules.
I also preferred having an auto-summary of the sub packages instead of a
toctree, but this could be made optional or discussed. :)
Further improvement could be also one file per class, but maybe that is to
detailed.
I would be glad, if I could improve the software for everybody with my
changes. If you have any question, just ask. Probably I did not explain
some of my problems in an understandable way.
Thank you for your time
Mario Michael Krell
--
You received this message because you are subscribed to the Google Groups
sphinx-dev group.
To view this discussion on the web visit
https://groups.google.com/d/msg/sphinx-dev/-/eWbnNTe6F_IJ.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
# -*- coding: utf-8 -*-
sphinx.apidoc
~
Parses a directory tree looking for Python modules and packages and creates
ReST files appropriately to create code documentation with Sphinx. It also
creates a modules index (named modules.suffix).
This is derived from the sphinx-autopackage script, which is:
Copyright 2008 Soci?t? des arts technologiques (SAT),
http://www.sat.qc.ca/
:copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
import os
import sys
import optparse
from os import path
# automodule options
if 'SPHINX_APIDOC_OPTIONS' in os.environ:
OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',')
else:
OPTIONS = [
'members',
'undoc-members',
# 'inherited-members', # disabled because there's a bug in sphinx
'show-inheritance',
]
INITPY = '__init__.py'
def makename(package, module):
Join package and module with a dot.
# Both package and module can be None/empty.
if package:
name = package
if module:
name += '.' + module
else:
name = module
return name
def write_file(name, text, opts):
Write the output file for module/package name.
fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix))
if opts.dryrun:
print 'Would create file %s.' % fname
return
if not opts.force and path.isfile(fname):
print 'File %s already exists, skipping.' % fname
else:
print 'Creating file %s.' % fname
f = open(fname, 'w')
try:
