-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 André schrieb: > Hi everyone, > > Apologies in advance for the long message; I need to make sure all the > relevant context is given. > > I've started the migration of the documentation for Crunchy (http:// > code.google.com/p/crunchy) to make use of Sphinx. In the process, I > plan to add some new directives and thought they might be a useful > addition to Sphinx. Rather than come up with some arbitrary "syntax" > for the new directives, I thought it would be wise to ask on this list > for suggestions - especially if there was interest to include the code > within the normal Sphinx distribution. > > There are two sets of new directives I am considering for Sphinx - and > currently using with Crunchy itself. > > The first is currently called (for Crunchy use) "getpythonsource" and, > in its simplest form, is used as follows: > > .. getpythonsource:: relative/path/to/module.object > > It uses the inspect module to extract the source code for "object" > from "module.py. One can simply use > > .. getpythonsource:: relative/path/to/module > > and the whole module will be included. In this way, it is a (partial) > duplication of the existing "literalinclude" directive. However, it > is clearly something that is Python specific and does not rely on > knowing (or keeping track) of line numbers in a file to include the > source of a specific "object". > > The object inclusion can even go to deeper levels such as > > .. getpythonsource:: relative/path/to/module.class.method ... > > i.e. anything supported by the inspect module. > > Before I introduce the second directive used by Crunchy, I should > perhaps explain briefly what Crunchy is or does for people who are not > familiar with it. Crunchy takes a static html (or rst) file and > displays it within a browser window, adding "interactive elements", > usually below code samples. The simplest interactive element is a > Python interpreter: one can type in and execute Python code within the > browser (Firefox) window and see the result back within the window. > Crunchy detects relevant code samples as being inside html <pre> and > use this to transform the page before feeding it to the browser. One > can gives more precise instructions to Crunchy as to which interactive > element to include by using the title attribute, such as > <pre title="editor linenumber">, which would include an editor below > the code sample, numbering the original code above, including a copy > of the code within the editor (so that it could be changed and/or > saved to a file, etc). It would also include a "code execution" > button so that the code could be run by a Python interpreter as a > normal script. There are a number of other interactive elements that > one could include (doctest, unittest, ...) with some "very little > added markup" (vlam) inserted in the title attribute. [Of course, if > I may state the obvious, such interactive object is only relevant for > html files to be viewed within a browser; this vlam would be totally > irrelevant for pdf documents, etc.] > > So... the other directive supported by Crunchy for reStructuredText > file is: > > .. crunchy:: vlam > > which is normally followed by some python code to be inserted in a > <pre> element. Note that the getpythonsource directive above can > also include vlam via: > > .. getpythonsource:: relative/path/to/module.object vlam > > ===== > For my modification to sphinx, I see a few choices. The simplest (for > me and to use only for my own purpose) is to simply add the two > directives above as I already have the code working. However that is > not very interesting ... > > Another option might be to make some changes to existing directives > used by Sphinx. One possible choice would be to add an option to code- > blocks as: > > .. code-block:: python > :crunchy: vlam > > and/or one of the two options (in bracket): > > .. code-block:: python > :getsource: relative/path/to/module.object [vlam] > [:crunchy: vlam] > > I believe that these would not break any existing code and so would be > totally transparent to the current sphinx users. However, since I am > just starting to use sphinx, this may not be the best way to proceed. > > Does any one have suggestions as to what would be the best > approach? Also, would there be interest in such an addition for > Sphinx? (if so, I am not asking for others to write the code, I am > volunteering to do it myself and contribute :-)
First, I also think these rather specific directives are best contained in a Crunchy-specific extension. Sphinx 0.6 also already contains something like .. getpythonsource:: as the :object: option of literalinclude. It's probably not working correctly in all cases, but you should be able to adapt the code to your needs. (If you haven't already written all that code anyway, sorry for answering this late...) cheers, Georg -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.11 (GNU/Linux) iEYEARECAAYFAkr3Uk8ACgkQN9GcIYhpnLA0owCgr3lD/3XBEVPwRTrKLHIN7leo LmQAnRCwy7Sj/MonQcKLeJ7HbRKcVU1a =TkhK -----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 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 -~----------~----~----~----~------~----~------~--~---
