-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Am 01.02.2010 02:16, schrieb [email protected]:
>
> I would like to generate printed Python documentation in my own very compact
> spartan format ("save a tree!"). Since I'm quite familiar with LaTex etc., if
> I
> could run just the parser on the sources of the standard Python documentation
> (for instance, on the tutorial), then I would use the resulting tree as a
> driver to generate my latex output.
>
> I have installed and tested docutils, and run quicktest.py on a few snippets
> of
> code, but as soon as I use markup using Python-specific roles such as :file:,
> :ref:, :option:", or such I get an error. So I need a more comprehensive setup
> that knows specifically about Python-specific (or sphinx-specific) markup.
>
> I installed sphinx and ran it on Python docs sources, and I get the Latex OK.
> So the know-how about Python "roles" and all that is there. If I could just
> stop sphinx at the point where it has produced the parsing tree I'll be
> happy. How do I do that?
>
> I do not need handholding; I'm quite conversant with processing structured
> documentation and making parsers and interpreters, but I'm ignorant of the way
> things are configured for a custom Sphinx run. A pointer to relevant
> documentation, a running example, the annotated setup of a project, or
> anything
> that would allow me to capture the parsing tree would be of great help and
> save
> me an enormous amount of time.
Hi,
for your purposes, if I understand them correctly, I think it would be best if
you adapted the Sphinx LaTeX writer (see sphinx/writers/latex.py) which
traverses a parse tree and generates LaTeX markup from them. The writer is
instantiated by the Builder (see sphinx/builders/latex.py). The builder's job
is to process all source files and pass them to the writer accordingly; in the
case of LaTeX output, all source trees belonging to one output .tex file are
combined and then fed to the writer.
If you ask where the trees come from: each file is parsed by Docutils in the
BuildEnvironment (see sphinx/environment.py), and then cached on disk (since
holding all trees in memory is not possible for documentation the size of the
Python docs). Upon writing, the trees are loaded from disk again, and
references between files are resolved (they cannot be resolved until all files
have been read in).
Back to the writer: Currently there is no API to replace the writer that the
latex builder uses, however, it is possible to monkey-patch a new writer into
the builder module using something like this::
from sphinx.writers.latex import LaTeXWriter
class MyLaTeXWriter(LaTeXWriter):
# override methods etc.
import sphinx.builders.latex
sphinx.builders.latex.LaTeXWriter = MyLaTeXWriter
If exchanging the Writer is not sufficient for your needs, please let me know.
cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (GNU/Linux)
iEYEARECAAYFAktmmqcACgkQN9GcIYhpnLBuYQCgjLE1scutOxwYrzBtUPvkRivr
IW4An3+Cc3xzV3qUrwa57VJmDMK4HVKQ
=N3mn
-----END PGP SIGNATURE-----
--
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.
