On 2009-03-09, Georg Brandl wrote: > Guenter Milde schrieb: >> the new version of the PyLit documentation at http://pylit.berlios.de >> is generated by Sphinx.
> Great! I wonder if there could be an integration of PyLit into Sphinx, so > that literate docs are extracted automatically before a build. With PyLit, you usually do not "extract" docs, but bring the source in (reStructured) text format. However, as there might be both literate and non-literate *.py sources in the source tree, it is not sensible to auto-convert all of them. However, if there are *.py.txt sources in text format, it would be sensible to call pylit.main() on the corresponding *.py file. This will by default update the text source if the code source is more recent. OTOH, you might want to extract the documentation and skip the code parts (instead of citing them). This is possible as well with the -s option (or defaults.strip = True). With auto-update, the strip-code option would need to be set in conf.py. >> While moving, I found some problems and ideas: >> * RCS/CVS/SVN keywords in bibliographic fields are cleaned up by the >> standard docutils writers but not by Sphinx. > That's true, since Sphinx doesn't consider them bibliographic fields. > Could use some work in this area. A maybe related problem is that sub-titles are not recognised but treated as a normal heading. >> * make linkcheck returns warnings of the form >> WARNING: ../usage/index.html - malformed! >> WARNING: download/index:79: malformed link: ../usage/index.html >> WARNING: pylit_test.py - malformed! >> WARNING: examples/index:118: malformed link: pylit_test.py >> for all internal links (be they valid or not). > In Sphinx, you should use :ref:, :doc: (and :download: for non-source files) > to link between pages. (The reason being that this is portable to LaTeX.) However, this is incompatible to standard docutils. >> What I would really like is a tool to: >> * Check internal links >> (Report error, if "usage/index.html" is not in the build tree). >> * Copy linked files from source to build-directory if this "fixes" >> a link. >> (Try to copy "source/examples/pylit_test.py" to >> "build/html/examples/pylit_test.py", report error if this fails.) > Try :download: (needs Sphinx trunk) for this. Actually, I would prefer the standard syntax with the behaviour of :download: if appropriate. In contrast to internal links to other parts of the documentation, the .html vs. .pdf problem is no problem here. >> * Due to the extended syntax, the rst documents can no longer be compiled >> by Docutils, so a standalone html writer would be a nice thing to have >> too. > What would the standalone HTML writer output? HTML, of course. Without the sidebar and navigation links, but with the "goodies" like syntax highlight and not failing on any of the extensions (custom directives and roles). It would need some sensible fallbacks (e.g. simple ignoring or "decorating" with a class) for constructs that do not make much sense in the standalone context. Use cases: * When working on the documentation, it is quite often desirable to compile and look at the result (or to find out if it compiles at all). Compiling just the current document is faster. * A file that should be usable both as part of the documentation "project" and as a single document, e.g. the examples in my PyLit documentation. Currently, they do not use any of the Sphinx extensions in order to be compilable by rst2html. Günter --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
