Hi folks --
Right now, my #1 complaint about the otherwise-amazingly-excellent
Sphinx is the "noise" of references in the marked-up text files. One
of the goals of plain-text markup languages like reST is to still be
readable in the plain text form, but unfortunately I'm finding the
verbosity of references can make the text hard to follow.
Part of this is Django's fault: parts of Django have pretty deeply
nested packages, so a reference like
``:meth:`django.contrib.comments.models.Comment.save``` is par for the
course. But still, that can make the text hard to follow; consider a
paragraph like::
You can access :attr:`~django.forms.Form.errors` without having to call
:meth:`~django.forms..Form.is_valid` first. The form's data will be
validated the first time either you call :meth:`~django.forms.Form.is_valid`
or access :attr:`~django.forms.Form.errors`.
That's 260 characters, about 100 of which are markup. A signal/noise
ratio of 2:1 just makes me unhappy.
I've been mulling over ways of fixing this for a long time, and
haven't had much luck. I've tried:
* Using ``.. currentmodule::`` to switch around frequently as needed.
This works OK -- it'd remove the "django.forms" bits from the above
example -- but fails when some text needs to describe objects that
live in different places.
* Using ``replace`` to replace something like ``|Form.save|`` with the
full reference; this doesn't seem to work (it fails with a message
about the replace directive containing multiple paragraphs). This also
isn't ideal because you need to redefine all the references over and
over in each file. When I say ``|Form.save|`` 99% of the time I'm
talking about a particular method, so something with global
substitutions would be better.
* Using a preprocess hook and regexes to do my own substitution of
``|replacements|`` from a global definitions file. This works the way
I'd like it to work -- I have a global subs file (currently in YAML),
and I get that behavior across all the content. But I'm stuck doing
this as text munging, which mean regexes, which means now I have two
problems.
Is there a better approach? I'm trying to avoid patching Sphinx here,
but if the answer is that a change to the core is needed, point me in
the right direction and I'm happy to submit a patch.
Thanks!
Jacob
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
