Guenter Milde schrieb: > Dear Sphinx developers, dear Georg, > > the new version of the PyLit documentation at http://pylit.berlios.de > is generated by Sphinx. > > PyLit (Python Literate) provides a plain but efficient tool for > literate programming: a `bidirectional text/code converter`_. > > .. _bidirectional text/code converter: features.html#dual-source > > The idea is that you do not document programs (after the fact), but > write documents that *contain* the programs. > > -- John Max Skaller
Great! I wonder if there could be an integration of PyLit into Sphinx, so that literate docs are extracted automatically before a build. > Converting the docs and examples was a nice experience and convinced me > that Sphinx and PyLit are a good match for a "pythonic" approach to > literate programming. > > 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. > > > http://docutils.sf.net//docutils/docs/ref/rst/restructuredtext.html#rcs-keywords That's true, since Sphinx doesn't consider them bibliographic fields. Could use some work in this area. > * 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.) > 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. > * 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? cheers, Georg --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
