Menu
▾
▴
docutils-users — General discussions, questions, help requests.
You can subscribe to this list here.
| 2002 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
(3) |
Sep
(15) |
Oct
(21) |
Nov
(18) |
Dec
(59) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2003 |
Jan
(43) |
Feb
(35) |
Mar
(78) |
Apr
(65) |
May
(163) |
Jun
(169) |
Jul
(137) |
Aug
(77) |
Sep
(47) |
Oct
(27) |
Nov
(43) |
Dec
(68) |
| 2004 |
Jan
(61) |
Feb
(39) |
Mar
(11) |
Apr
(42) |
May
(86) |
Jun
(82) |
Jul
(24) |
Aug
(26) |
Sep
(37) |
Oct
(62) |
Nov
(131) |
Dec
(43) |
| 2005 |
Jan
(31) |
Feb
(56) |
Mar
(65) |
Apr
(165) |
May
(106) |
Jun
(97) |
Jul
(65) |
Aug
(150) |
Sep
(78) |
Oct
(115) |
Nov
(41) |
Dec
(26) |
| 2006 |
Jan
(50) |
Feb
(39) |
Mar
(56) |
Apr
(67) |
May
(89) |
Jun
(68) |
Jul
(116) |
Aug
(65) |
Sep
(58) |
Oct
(103) |
Nov
(28) |
Dec
(52) |
| 2007 |
Jan
(92) |
Feb
(60) |
Mar
(124) |
Apr
(96) |
May
(69) |
Jun
(79) |
Jul
(25) |
Aug
(22) |
Sep
(7) |
Oct
(17) |
Nov
(27) |
Dec
(32) |
| 2008 |
Jan
(57) |
Feb
(87) |
Mar
(51) |
Apr
(43) |
May
(56) |
Jun
(62) |
Jul
(25) |
Aug
(82) |
Sep
(58) |
Oct
(42) |
Nov
(38) |
Dec
(86) |
| 2009 |
Jan
(50) |
Feb
(33) |
Mar
(84) |
Apr
(90) |
May
(109) |
Jun
(37) |
Jul
(22) |
Aug
(51) |
Sep
(93) |
Oct
(86) |
Nov
(31) |
Dec
(62) |
| 2010 |
Jan
(33) |
Feb
(57) |
Mar
(62) |
Apr
(43) |
May
(30) |
Jun
(49) |
Jul
(20) |
Aug
(40) |
Sep
(152) |
Oct
(38) |
Nov
(15) |
Dec
(32) |
| 2011 |
Jan
(29) |
Feb
(25) |
Mar
(65) |
Apr
(45) |
May
(27) |
Jun
(11) |
Jul
(14) |
Aug
(8) |
Sep
(13) |
Oct
(117) |
Nov
(60) |
Dec
(19) |
| 2012 |
Jan
(23) |
Feb
(32) |
Mar
(24) |
Apr
(41) |
May
(56) |
Jun
(24) |
Jul
(15) |
Aug
(11) |
Sep
(26) |
Oct
(21) |
Nov
(12) |
Dec
(31) |
| 2013 |
Jan
(32) |
Feb
(24) |
Mar
(39) |
Apr
(44) |
May
(44) |
Jun
(8) |
Jul
(9) |
Aug
(12) |
Sep
(34) |
Oct
(19) |
Nov
(5) |
Dec
(9) |
| 2014 |
Jan
(22) |
Feb
(12) |
Mar
(7) |
Apr
(2) |
May
(13) |
Jun
(17) |
Jul
(8) |
Aug
(10) |
Sep
(7) |
Oct
(4) |
Nov
|
Dec
(39) |
| 2015 |
Jan
(13) |
Feb
(12) |
Mar
(12) |
Apr
(40) |
May
(5) |
Jun
(22) |
Jul
(3) |
Aug
(42) |
Sep
(5) |
Oct
(10) |
Nov
|
Dec
(10) |
| 2016 |
Jan
(9) |
Feb
(43) |
Mar
(5) |
Apr
(14) |
May
(17) |
Jun
(5) |
Jul
(5) |
Aug
(22) |
Sep
(5) |
Oct
|
Nov
(4) |
Dec
(18) |
| 2017 |
Jan
(28) |
Feb
(29) |
Mar
(9) |
Apr
(23) |
May
(48) |
Jun
(5) |
Jul
(32) |
Aug
(9) |
Sep
(13) |
Oct
(13) |
Nov
(6) |
Dec
(4) |
| 2018 |
Jan
(6) |
Feb
(5) |
Mar
(1) |
Apr
(2) |
May
(5) |
Jun
(17) |
Jul
(12) |
Aug
(15) |
Sep
|
Oct
(2) |
Nov
|
Dec
|
| 2019 |
Jan
|
Feb
(6) |
Mar
(3) |
Apr
(5) |
May
(10) |
Jun
(6) |
Jul
(6) |
Aug
|
Sep
(11) |
Oct
(18) |
Nov
(10) |
Dec
(7) |
| 2020 |
Jan
(3) |
Feb
(14) |
Mar
(2) |
Apr
(1) |
May
(5) |
Jun
|
Jul
(1) |
Aug
(11) |
Sep
(8) |
Oct
|
Nov
(1) |
Dec
(14) |
| 2021 |
Jan
(7) |
Feb
(2) |
Mar
(1) |
Apr
(8) |
May
(23) |
Jun
(7) |
Jul
(10) |
Aug
(1) |
Sep
|
Oct
(7) |
Nov
(10) |
Dec
(2) |
| 2022 |
Jan
|
Feb
(21) |
Mar
|
Apr
(3) |
May
(7) |
Jun
(4) |
Jul
(1) |
Aug
|
Sep
(3) |
Oct
|
Nov
|
Dec
|
| 2023 |
Jan
(18) |
Feb
|
Mar
(1) |
Apr
|
May
(9) |
Jun
|
Jul
|
Aug
(5) |
Sep
|
Oct
|
Nov
|
Dec
|
| 2024 |
Jan
|
Feb
(2) |
Mar
(3) |
Apr
(5) |
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
(2) |
Nov
|
Dec
(2) |
| 2025 |
Jan
(4) |
Feb
|
Mar
(2) |
Apr
(1) |
May
(3) |
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
|
1
(1) |
2
|
3
|
4
(1) |
5
(2) |
6
(4) |
7
(3) |
|
8
(5) |
9
|
10
|
11
|
12
|
13
|
14
|
|
15
(2) |
16
|
17
|
18
|
19
|
20
|
21
|
|
22
(1) |
23
|
24
|
25
(3) |
26
(4) |
27
|
28
|
|
29
|
30
|
31
(1) |
|
|
|
|
|
From: Sih Iok-J. <iok...@co...> - 2011-05-31 03:32:06
|
Dear All,
python-doctuils Version: 0.7-2
I would like to use rst2latex to generate *.tex file , and show the
section name on the right top of result PDF file.
So, I use the fancyhdr Latex package to accomplish my goal.
But the result PDF file doesn't show the section name on the right top.
Only show "TABLE OF CONTENT" string at the right top.
the default tex file that rst2latex generated seem like doest't add section info
for Latex fancyhdr packages
Is there any advise for my question ?
the following is my docutils.conf and docutils.tex (Latex stylesheet)
docutils.conf
-----------------
[latex2e writer]
documentclass: article
documentoptions: 12pt,a4paper,dvipdfmx
output-encoding: utf-8
stylesheet: docutils.tex
docutils.tex
-------------
\usepackage[top=2.54cm, bottom=2.54cm, left=2.54cm, right=2.54cm]{geometry}
\usepackage{fancyhdr}
\usepackage{fncychap}
\pagestyle{fancy}
\renewcommand{\sectionmark}[1]{\markboth{}{\thesection. \ #1}}
\fancyhead[LO,L]{\leftmark}
\fancyhead[RO,R]{\rightmark}
\fancyfoot[CO,C]{\thepage}
My PDF generate step
----------------------
rst2latex foo.rst foo.tex
latex foo.tex
latex foo.tex
dvipdfmx foo.dvi
Regards,
Sih, Io̍k-Jîn
|
|
From: David S. <dav...@ch...> - 2011-05-26 07:40:24
|
I'm using rst2pdf to make slide-shows, and would like to include images from
different parts of my file system. If I write the full directory tree into the
image line, all is well. I would however like to define the tree elsewhere, as
e.g. |FIGS|, and use this. Is this possible? Here's an example that doesn't work:
.. image:: |FIGS|/Figure_Ndep.png
:width: 80%
.. |FIGS| replace:: /home/fred/Documents/NicePics
Is there a way to get this working? Thanks. (Sorry if this is a noob question. I
am new to rst)
|
|
From: Guenter M. <mi...@us...> - 2011-05-26 06:34:38
|
On 2011-05-22, Greg Orlowski wrote: > Hi, I'm a new docutils + reST user. I started learning reST just this > week with the aim of using it to write blog posts and other > documentation. Welcome Greg, > I created a github project with some wrapper scripts that do the following: > - add a ``..code-block:: language_name" directive that writes out code > blocks as <pre class="brush: language_name">...</pre> for use with > SyntaxHighlighter. I saw other projects that use pygments and some > other workflow steps for code syntax highlighting, but I like the look > + feel + extensive language support of SH. You could consider the shorter name ``..code::`` as a directive always implies a block (I learned this implementing the "math" role and directive). For compatibility, the aliases "code-block" and "sourcecode" could be defined. > - includes a wrapper script to go from rst -> html -> open in a web > browser to preview your reST. This is pretty rudimentary and I'm sure > others have written the same thing. My script includes a template in > the flow that adds SyntaxHighlighter js scripts + css to the <head>. > - includes simple custom VIM commands to add "preview as HTML in web > browser," "copy output HTML to clipboard," and "validate reST" > commands in vim. > I'm going to poke around at other similar tools to add a couple more > features when I get a better feel for how I'd like to improve my > workflow. > My git project is here: > https://github.com/gorlowski/reStructuredText-Blog-Authoring-Tools If you feel it is ready for more public exposure and going to be a long-term project, consider supplying a patch to ``docutils/docs/user/links.txt``. > One question I have: what is the best way to generate html that > excludes everything outside the <body><div ...>ONLY INCLUDE THIS > STUFF</div></body>? Where is the best place to add a little python to > exclude the outer stuff when invoking rst2html? I am currently doing a > hackish filter through sed in a bash wrapper to strip it out. This seems to become a FAQ ;-) Luc Saffre just posted a link to his solution: http://code.google.com/p/lino/source/browse/lino/utils/restify.py#73 If this turns out to be the same request and useful for other users too, we could consider support in the standard html writer. > I call rst2html from a bootstrap wrapper python script that registers > my custom ..code-block directive. Could I put something in this > bootstrap process to change the writer? Yes. You might have a look at http://docutils.sourceforge.net/docs/api/cmdline-tool.html > Should I use a custom template file to exclude the wrapper stuff? If you mean the > template in the flow that adds SyntaxHighlighter js scripts + css > to the <head>. you could try whether this fits in a custom template and set it as default value of the "template" option in the wrapper script. Alternatively, create/use a custom HTML writer. Günter |
|
From: Guenter M. <mi...@us...> - 2011-05-26 06:06:37
|
On 2011-05-26, Eli Bendersky wrote: > Hello, > I have a relatively large page edited with ReST which contains a lot > of links. Some of the links should really have the name text but point > to different external targets, something like: > Bla bla `foo <http://baz>`_ bla bla `foo <http://bar>`_. > Is this possible? Yes, with anonymous references:: Bla bla `foo <http://baz>`__ bla bla `foo <http://bar>`__. Günter |
|
From: Eli B. <el...@gm...> - 2011-05-26 03:37:54
|
Hello, I have a relatively large page edited with ReST which contains a lot of links. Some of the links should really have the name text but point to different external targets, something like: Bla bla `foo <http://baz>`_ bla bla `foo <http://bar>`_. Is this possible? Thanks in advance Eli |
|
From: Ben F. <fo...@uc...> - 2011-05-25 23:40:57
|
Hi,
I am *not* subscribed, but would appreciate any replies.
I am using Sphinx document generator with reST to make a
User's Guide for a GCM model, and need to display some images
in external links. If I hardwire the URL as an argument to
the image directive, it works fine, e.g.:
.. image:: http://myurl/pict0001.png
And my image is nicely displayed. However, I do not want to
hardwire the base of this url into many 10's or 100's of image
directives, i.e., I will want to deploy the user's guide where
the url's to the images would be different. (I may have several
images in one URL, e.g., pict0001.png to pict0050.png)
I tried using the Sphinx "extlinks" extension, e.g.:
extlinks = {'data_url': ('http://myurl/%s', 'data_url ')}
.. image:: :data_url:`My picture <pict0001.png>`
but this is ignored by the image directive (works fine elsewhere).
This would be best, because I can use the data_url and add the
image names pict0001.png, pict0002.png,...
So I have also tried both replacement:
.. |pict0001| replace:: http://myurl/pict0001.png
.. image:: |mypict|
and substitution:
.._`pict0001`:
http://myurl/pict0001.png
.. image:: `pict0001`
These all work inside inline text, but they all fail as an argument
to the image directive. Help?? Thanks,
--Ben Foster
fo...@uc...
|
|
From: Luc S. <luc...@gm...> - 2011-05-25 22:28:29
|
On 26.05.2011 0:05, Luc Saffre wrote: > On 7.05.2011 21:43, Guenter Milde wrote: >> You could inherit from the standard html writer and overwrite the >> methods inserting the unwanted tags. See e.g. the html4trans >> and html4strict writers in the sandbox for examples. > > Thanks for your answer (and sorry for reacting only now). I still feel > very overwhelmed by docutils' complexity, but now I'll have to dig into > this because my workaround turned out to fail in some cases (the > surrounding DIV tag may have an id attribute as well. Uff, I got it! Thanks again for your hint. My code is here: http://code.google.com/p/lino/source/browse/lino/utils/restify.py#73 Luc |
|
From: Luc S. <luc...@gm...> - 2011-05-25 21:05:25
|
On 7.05.2011 21:43, Guenter Milde wrote: > You could inherit from the standard html writer and overwrite the > methods inserting the unwanted tags. See e.g. the html4trans > and html4strict writers in the sandbox for examples. Thanks for your answer (and sorry for reacting only now). I still feel very overwhelmed by docutils' complexity, but now I'll have to dig into this because my workaround turned out to fail in some cases (the surrounding DIV tag may have an id attribute as well. Luc |
|
From: Greg O. <gre...@ya...> - 2011-05-22 01:21:41
|
Hi, I'm a new docutils + reST user. I started learning reST just this week with the aim of using it to write blog posts and other documentation. I created a github project with some wrapper scripts that do the following: - add a ``..code-block:: language_name" directive that writes out code blocks as <pre class="brush: language_name">...</pre> for use with SyntaxHighlighter. I saw other projects that use pygments and some other workflow steps for code syntax highlighting, but I like the look + feel + extensive language support of SH. - includes a wrapper script to go from rst -> html -> open in a web browser to preview your reST. This is pretty rudimentary and I'm sure others have written the same thing. My script includes a template in the flow that adds SyntaxHighlighter js scripts + css to the <head>. - includes simple custom VIM commands to add "preview as HTML in web browser," "copy output HTML to clipboard," and "validate reST" commands in vim. I'm going to poke around at other similar tools to add a couple more features when I get a better feel for how I'd like to improve my workflow. My git project is here: https://github.com/gorlowski/reStructuredText-Blog-Authoring-Tools One question I have: what is the best way to generate html that excludes everything outside the <body><div ...>ONLY INCLUDE THIS STUFF</div></body>? Where is the best place to add a little python to exclude the outer stuff when invoking rst2html? I am currently doing a hackish filter through sed in a bash wrapper to strip it out. I call rst2html from a bootstrap wrapper python script that registers my custom ..code-block directive. Could I put something in this bootstrap process to change the writer? Should I use a custom template file to exclude the wrapper stuff? cheers, -Greg |
|
From: Guenter M. <mi...@us...> - 2011-05-15 21:12:52
|
On 2011-05-15, Borsuk Euroazjatycki wrote: > Hello > There is a small (but sufficient) number of CV's (and resumes) written > in reStructuredText. However, I can't find any covering letter > examples. I have trouble achieving the right visual form - putting > text into upper left / upper right corner, centering text, and so on. > I'm especially interested in .pdf (rst2latex) and html output formats. > To get an idea of what I would like to achieve, look here: > http://www.rpi.edu/dept/arc/training/latex/resumes/let3.pdf > http://www.rpi.edu/dept/arc/training/latex/resumes/let7.pdf > http://www.rpi.edu/dept/arc/training/latex/resumes/let9a.pdf > http://www.rpi.edu/dept/arc/training/latex/resumes/let9b.pdf > http://www.rpi.edu/dept/arc/training/latex/resumes/ > Also, I need tips tweaking the vertical space between individual > sections of a document, for both pdf and html. So far I'm using a > crude technique - lots of preformatted blocks. > Assume I have fair knowledge of HTML and basic LaTeX skills. Can you > give me any hints ? I don't think rst is the right tool for this task. If you insist, you could try with lots of class arguments and styling in style sheets. Also, see in the "Docutils directives" documentation if there are any directive that can be (ab)used to place text in the corners... Günter |
|
From: Borsuk E. <ja...@gm...> - 2011-05-15 11:11:21
|
Hello There is a small (but sufficient) number of CV's (and resumes) written in reStructuredText. However, I can't find any covering letter examples. I have trouble achieving the right visual form - putting text into upper left / upper right corner, centering text, and so on. I'm especially interested in .pdf (rst2latex) and html output formats. To get an idea of what I would like to achieve, look here: http://www.rpi.edu/dept/arc/training/latex/resumes/let3.pdf http://www.rpi.edu/dept/arc/training/latex/resumes/let7.pdf http://www.rpi.edu/dept/arc/training/latex/resumes/let9a.pdf http://www.rpi.edu/dept/arc/training/latex/resumes/let9b.pdf http://www.rpi.edu/dept/arc/training/latex/resumes/ Also, I need tips tweaking the vertical space between individual sections of a document, for both pdf and html. So far I'm using a crude technique - lots of preformatted blocks. Assume I have fair knowledge of HTML and basic LaTeX skills. Can you give me any hints ? |
|
From: David G. <go...@py...> - 2011-05-08 19:55:44
|
On Sunday, May 8, 2011, Andrew Dalke <da...@da...> wrote: > Hi David, > >> There are any number of ways to document a dictionary return value. >> ... >> But I think you're asking in the wrong place. reST provides markup >> primitives, but does not provide any conventions for >> autodocumentation. > > No doubt that I am. I'm quite confused about what's going on, that is: > > - the role of docutils vs. sphinx Sphinx is a layer on top of Docutils, higher level. Sphinx does autodocumentation (among other things), Docutils does not (although it was once my goal for Docutils also). > - your active/informational PEP 257 but rejected PEP 258 PEP 257 is about docstring syntax and tool-independent formatting conventions, while PEP 258 was a grand design spec (or vision) for Docutils, not fully implemented. 258 is marked rejected simply because standard library inclusion is no longer part of the plan. > - the existence of a few reST docstrings in the standard library > *and* a few @param docstrings in trace.py > > (Okay, the last is likely historical cruft.) Cruft or individual whim. >> I suggest you look at the Sphinx docs and/or ask on the Sphinx mailing >> lists. > > I will do that - thanks for the pointer Any time. David -- David Goodger <http://python.net/~goodger> |
|
From: Andrew D. <da...@da...> - 2011-05-08 19:17:16
|
Hi David,
> There are any number of ways to document a dictionary return value.
> ...
> But I think you're asking in the wrong place. reST provides markup
> primitives, but does not provide any conventions for
> autodocumentation.
No doubt that I am. I'm quite confused about what's going on, that is:
- the role of docutils vs. sphinx
- your active/informational PEP 257 but rejected PEP 258
- the existence of a few reST docstrings in the standard library
*and* a few @param docstrings in trace.py
(Okay, the last is likely historical cruft.)
> I suggest you look at the Sphinx docs and/or ask on the Sphinx mailing
> lists.
I will do that - thanks for the pointer
Andrew
da...@da...
|
|
From: David G. <go...@py...> - 2011-05-08 14:49:50
|
On Sat, May 7, 2011 at 17:55, Andrew Dalke <da...@da...> wrote: > I'm trying to understand reST well enough to figure out if it's > appropriate for a project I'm working on. I've not worked with reST > before so I've been reading the documentation, but I don't see how I > can use it as-is for my case. > > The main problem is that when I have functions which return a > dictionary, I want to document the contents of the dictionary. For > example, the key "nAtoms" has the value "the number of atoms in the > molecule." > > I haven't found much information at all about how to document return > types in reST, much less complex examples. The few ones I found, > which come from the Python source, looked like: > > :return: Path to the resulting byte compiled file. ... > that is, single line describing a relatively simple object. > > > I think there isn't a standard way to document complex object with > reST so the right solution is to forge my own path and do something > like: ... > Is there an existing solution for this problem, and if so, what is > it? > > If not, does this sound right, and how do I go about having sphinx > recognize those fields and including them in the documentation? There are any number of ways to document a dictionary return value. As a field list, bullet list, definition list, table, etc. But I think you're asking in the wrong place. reST provides markup primitives, but does not provide any conventions for autodocumentation. The closest we ever got in the Docutils project was in "Docstring Semantics" (not implemented): http://docutils.sourceforge.net/docs/dev/semantics.html I suggest you look at the Sphinx docs and/or ask on the Sphinx mailing lists. The Sphinx project is all about the higher-level issues, including autodocumentation conventions. -- David Goodger <http://python.net/~goodger> |
|
From: Andrew D. <da...@da...> - 2011-05-08 06:09:53
|
On May 8, 2011, at 3:24 AM, Ben Finney wrote:
> Don't return a dict in that case. Instead, define a type for this
> complex object, give it a meaningful name and docstring, and refer to it
> by name.
I had hoped in my short context description at the end of my post
to imply that there is no meaningful name for the return types of
individual functions.
Here's a more fleshed out example which I think shows the heart
of what I'm trying to do. Rather than working with molecules,
this example computes properties of strings.
There is a dependency chain:
strlen depends on s
lc depends on s (this is the lower-case version of s)
a depends on lc (the number of times "a" or "A" is found in s)
e depends on lc
i depends on lc
o depends on lc
u depends on lc
and given that I have "s" and want "o", I'll write the dependency
handling code, caching all intermediate calculations.
===============================
import inspect
def strlen(s):
"""The length of the string"""
return len(s)
def lc(s):
"""the string in lowercase form"""
return s.lower()
def vowelcounts(lc):
"""Counts for the number of times the vowels [aeiouAEIOU] exist
:key a: The number of times a is found
:key e: The number of times e is found
:key i: The number of times i is found
:key o: The number of times o is found
:key u: The number of times u is found
"""
return dict((c, lc.count(c)) for c in "aeiuo")
class Properties(object):
def __init__(self, s, handlers):
self.cache = {"s": s}
self.handlers = handlers
def __getitem__(self, key):
try:
return self.cache[key]
except KeyError:
pass
handler = self.handlers[key]
# Recursively resolve the values this function needs as input parameters
args = (self[name] for name in inspect.getargspec(handler).args)
# Call it and figure out if it returned a single or multiple values
retval = handler(*args)
if isinstance(retval, dict):
self.cache.update(retval)
else:
self.cache[key] = retval
return self.cache[key]
===============================
Here it is in use.
>>> handlers = dict(strlen=strlen, lc=lc, a=vowelcounts, e=vowelcounts,
... i=vowelcounts, o=vowelcounts, u=vowelcounts)
>>> p = Properties("Is this Ohio?", handlers);
>>> p.cache
{'s': 'Is this Ohio?'}
>>> p["o"]
2
>>> p.cache
{'a': 0, 's': 'Is this Ohio?', 'e': 0, 'lc': 'is this ohio?', 'i': 3, 'u': 0, 'o': 2}
>>>
This is obviously fragile. There's a few ways I plan to make it
more robust. One is to scan the docstring and find the ":key:" (or
whatever) return types. This solves a few issues:
- I can easily determine if the handler computes a single
value or a set of values (lack of :key: means the first)
- At handler registration time I can easily figure out which
properties the function claims to handle, and therefore
do the correct dependency management.
In my API's current incarnation I do all of these with @descriptors
but didn't like how cumbersome it was nor how hard it was to
generate good documentation.
With this example it should be clear that the return type is
an implementation choice. That is, I could instead have
implemented the code in "vowelcounts" as
def a_count(lc):
"The number of times a is found"
return lc.count("a")
def e_count(lc):
"The number of times e is found"
return lc.count("e")
handlers = {... a: a_count, e: e_count ... }
and presented the same outward-facing API. In that API I would
like to have:
>>> p.describe("o")
The number of times o is found.
Suppose I did use individual return types, with documentation
as part of those types. Then I'll have
class VowelCounts(object):
"""Counts for the number of times the vowels [aeiouAEIOU] exist
:var a: The number of times a is found
:var e: The number of times e is found
:var i: The number of times i is found
:var o: The number of times o is found
:var u: The number of times u is found
"""
def __init__(self, a, e, i, o, u):
self.a = a
self.e = e
self.i = i
self.o = o
self.u = u
def vowelcounts(lc):
"""Count the number of times a vowel is found
:rtype: VowelCounts
""""
... implementation here ...
return VowelCounts(**dict((c, lc.count(c)) for c in "aeiuo"))
This is a lot of overhead compared to what I was thinking about,
if only because of the tedious __init__ section (namedtuple doesn't
help here because it has no docstring support), the implementation
of the collection step is more complicated and error-prone (ie,
I have to find "VowelCounts" in the rtype, assume it's in the
same module, and then parse its docstring), and the disassociation
between use and documentation means it's harder to find the
documentation for a given item. (Eg, search up or down?)
Plus, the data types will *never* be reused by another function,
so there's no savings in that regard.
I therefore just don't see your suggestion as being appropriate
for what I'm trying to do, and I hope my fleshed out example
shows why.
Andrew
da...@da...
|
|
From: Ben F. <ben...@be...> - 2011-05-08 01:25:21
|
Andrew Dalke <da...@da...> writes: > return dict(nAtoms = len(molecule.atoms), nBonds = len(molecule.bonds), > nHeavies = sum(1 for atom in molecule.atoms if molecule.atomic_number != 1)) > > > Is there an existing solution for this problem, and if so, what is it? Don't return a dict in that case. Instead, define a type for this complex object, give it a meaningful name and docstring, and refer to it by name. -- \ “… one of the main causes of the fall of the Roman Empire was | `\ that, lacking zero, they had no way to indicate successful | _o__) termination of their C programs.” —Robert Firth | Ben Finney |
|
From: Andrew D. <da...@da...> - 2011-05-07 21:55:10
|
I'm trying to understand reST well enough to figure out if it's appropriate for a project I'm working on. I've not worked with reST before so I've been reading the documentation, but I don't see how I can use it as-is for my case.
The main problem is that when I have functions which return a dictionary, I want to document the contents of the dictionary. For example, the key "nAtoms" has the value "the number of atoms in the molecule."
I haven't found much information at all about how to document return types in reST, much less complex examples. The few ones I found, which come from the Python source, looked like:
:return: Path to the resulting byte compiled file.
email/charset.py: :return: The encoded string, with RFC 2047 chrome.
email/charset.py: :return: Lines of encoded strings, each with RFC 2047 chrome.
email/quoprimime.py: :return: The length in bytes of the byte array when it is encoded with
email/quoprimime.py: :return: The length in bytes of the byte array when it is encoded with
py_compile.py: :return: Path to the resulting byte compiled file.
that is, single line describing a relatively simple object.
I think there isn't a standard way to document complex object with reST so the right solution is to forge my own path and do something like:
def compute_counts(molecule):
"""Compute atom and bond counts
:param molecule: A molecule object
:key nAtoms: The total number of atoms
:key nHeavies: The number of heavy (non-hydrogen) atoms
:key nBonds: The total number of bonds
"""
return dict(nAtoms = len(molecule.atoms), nBonds = len(molecule.bonds),
nHeavies = sum(1 for atom in molecule.atoms if molecule.atomic_number != 1))
Is there an existing solution for this problem, and if so, what is it?
If not, does this sound right, and how do I go about having sphinx recognize those fields and including them in the documentation?
For larger context, this project will end up defining several hundred such chemical property calculations, with an API which looks like:
properties = Properties(molecule, collection_of_functions)
print properties["nAtoms"]
During function collection, I want to read/parse the docstring and figure out which function computes which properties. In this case, "compute_counts" computes three properties, so the ["nAtoms"] __getitem__ forwards the call to that function.
I also want interactive help and printable documentation for all of the property calculation functions, and I think that if my API requires documentation in order to work then it's more likely that people will document what each thing means. (I learned this from R's packaging system.)
Andrew Dalke
da...@da...
|
|
From: Guenter M. <mi...@us...> - 2011-05-07 18:43:36
|
On 2011-05-07, Luc Saffre wrote:
> On 6.05.2011 15:51, Luc Saffre wrote:
>> The `html_body` function from docutils.examples wraps the whole output
>> into a <div class="document"> tag by default:
>>>>> from docutils.examples import html_body
>>>>> print html_body(u"Foo")
>> <div class="document">
>> <p>Foo</p>
>> </div>
>> Is there a option or setting to *not* have it create this wrapper tag? I
>> mean in the above example to have it create just::
>> <p>Foo</p>
> P.S. I currently use the following workaround. Very ugly, but it works
> for me::
> def my_html_body(s):
> html = html_body(s)
> assert html.startswith('<div class="document">\n')
> assert html.endswith('</div>\n')
> return html[23:-7]
You could inherit from the standard html writer and overwrite the
methods inserting the unwanted tags. See e.g. the html4trans
and html4strict writers in the sandbox for examples.
Günter
|
|
From: Luc S. <luc...@gm...> - 2011-05-07 05:13:45
|
On 6.05.2011 15:51, Luc Saffre wrote:
> The `html_body` function from docutils.examples wraps the whole output
> into a <div class="document"> tag by default:
>
>>>> from docutils.examples import html_body
>>>> print html_body(u"Foo")
> <div class="document">
> <p>Foo</p>
> </div>
>
> Is there a option or setting to *not* have it create this wrapper tag? I
> mean in the above example to have it create just::
>
> <p>Foo</p>
P.S. I currently use the following workaround. Very ugly, but it works
for me::
def my_html_body(s):
html = html_body(s)
assert html.startswith('<div class="document">\n')
assert html.endswith('</div>\n')
return html[23:-7]
Luc
|
|
From: Luc S. <luc...@gm...> - 2011-05-06 12:51:18
|
The `html_body` function from docutils.examples wraps the whole output into a <div class="document"> tag by default: >>> from docutils.examples import html_body >>> print html_body(u"Foo") <div class="document"> <p>Foo</p> </div> Is there a option or setting to *not* have it create this wrapper tag? I mean in the above example to have it create just:: <p>Foo</p> Luc |
|
From: Yunfan J. <jy...@gm...> - 2011-05-06 08:05:18
|
checked assemble_option_list and found its not help and i gave up, will first got the nodes tree, then use xml module to get what i need On Fri, May 6, 2011 at 2:58 PM, Guenter Milde <mi...@us...>wrote: > On 2011-05-06, Guenter Milde wrote: > > On 2011-05-05, Yunfan Jiang wrote: > > > But it should be relatively easy to write an utility function that, given > > the doctree or the docinfo node returns the fields as dictionary. > > assemble_option_dict() in utils.py might be exactly what you want. > > Günter > > > > ------------------------------------------------------------------------------ > WhatsUp Gold - Download Free Network Management Software > The most intuitive, comprehensive, and cost-effective network > management toolset available today. Delivers lowest initial > acquisition cost and overall TCO of any competing solution. > http://p.sf.net/sfu/whatsupgold-sd > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. > -- ME = { "name": [ "jyf", "yunfan", "wuxian" ], "im": { "gtalk": "jy...@gm...", "msn": "ge...@li..." }, "job": "python engineer", "site": "http://hi.baidu.com/jyf1987", "interested": { "tech": [ "linux", "python", "lua", "php", "html5", "c", "nosql"], "history": ["chinese history", "global history"], "SF": [ "hard SF", "Thought experiment" ], "music": [ "New Age", "Chinese old theme", "Electronic music", "Strange Music :}"] } } |
|
From: Guenter M. <mi...@us...> - 2011-05-06 06:59:13
|
On 2011-05-06, Guenter Milde wrote: > On 2011-05-05, Yunfan Jiang wrote: > But it should be relatively easy to write an utility function that, given > the doctree or the docinfo node returns the fields as dictionary. assemble_option_dict() in utils.py might be exactly what you want. Günter |
|
From: Guenter M. <mi...@us...> - 2011-05-06 06:08:42
|
On 2011-05-05, Yunfan Jiang wrote:
> [-- Type: text/plain, Encoding: quoted-printable --]
Dear Yunfan,
> well, i choice a
>> a) implement a "blog-writer" and use the field values in it
> as a lazy programmer, its best to use some tech like register a hook to got
> the target filedlist and then store the value to return
> this is neccessary on the statemachine lib
> but the rst parser implement ignore the context variable ,so any registed
> processer couldnt access the context to the statemachine
The doctree is interlinked and there are functions and arguments to
traverse it, e.g.:
:node.parent: points to the parent node so you can e.g. check for
inline vs. block level nodes with ::
def is_inline(self, node):
"""Check whether a node represents an inline element"""
return isinstance(node.parent, nodes.TextElement)
:node.traverse(): is the more general method to get related nodes, see
its documentation.
> the plan b might be a quick way , but it seems not directive, why not return
> a python dict instead of xml node tree?
>> b) convert to XML and use standard tools to extract the info,
>> or convert to a Docutils doctree and extract the info traversing
>> the tree (similar to what is done in the transforms
>> -> see docutils/docutils/transforms/*.py).
Until now, the need did not arise.
(How would you print the dict-based document tree?)
But it should be relatively easy to write an utility function that, given
the doctree or the docinfo node returns the fields as dictionary.
Günter
(no TOFU_, please)
.. _TOFU: http://en.wikipedia.org/wiki/Posting_style#Top-posting
|
|
From: Yunfan J. <jy...@gm...> - 2011-05-05 07:34:03
|
well, i choice a actually, i have checked some source code in docutils packages like statemachine and parser.rst as a lazy programmer, its best to use some tech like register a hook to got the target filedlist and then store the value to return this is neccessary on the statemachine lib but the rst parser implement ignore the context variable ,so any registed processer couldnt access the context to the statemachine the plan b might be a quick way , but it seems not directive, why not return a python dict instead of xml node tree? On Thu, May 5, 2011 at 3:22 PM, Guenter Milde <mi...@us...>wrote: > On 2011-05-04, Yunfan Jiang wrote: > > > hi, > > i got some knowledges here > > http://docutils.sourceforge.net/docs/howto/rst-directives.html while i > > am looking for the documents for developer > > Did you find the developer docs in the > http://docutils.sourceforge.net/docs/dev/ directory, too? > > > i am doing my own blog system which use rst as the main format, > > currently my target is to use a single rst file to contains all the > > field that a blog entry needs, like title, tags, uri_code, and content, > > and i want to store the title, tags, and uri_code in the file's > > FieldList like this > > >:title: the first blog of mine > >:uri_code: the-first-blog > >:tags: test python about > > > here is content > > > but the problem is i dont know how to parsing a reSturctured text and > > got the target field's value , there's so many documents that tolds how > > to translate from rst to another format ( html, xml, ...), could you > > show me same documents about this target, or could you give me some > > sample? > > This depends on what exactly you want to achieve. In any case you might > need to look at the source (in addition to the developers documentation). > > a) do you implement a "blog-writer" and want to use the field values in > them? > > -> have a look at html4css1/__init__.py or latex2e/__init__.py to see > how special field names are detected (hint: look at the > visit_docinfo() and visit_field_name() definitions). > > b) do you want to parse the rst source separtely? > > -> convert to XML and use standard tools to extract the info, > > or convert to a Docutils doctree and extract the info traversing > the tree (similar to what is done in the transforms > -> see docutils/docutils/transforms/*.py). > > Günter > > > > > > ------------------------------------------------------------------------------ > WhatsUp Gold - Download Free Network Management Software > The most intuitive, comprehensive, and cost-effective network > management toolset available today. Delivers lowest initial > acquisition cost and overall TCO of any competing solution. > http://p.sf.net/sfu/whatsupgold-sd > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. > -- ME = { "name": [ "jyf", "yunfan", "wuxian" ], "im": { "gtalk": "jy...@gm...", "msn": "ge...@li..." }, "job": "python engineer", "site": "http://hi.baidu.com/jyf1987", "interested": { "tech": [ "linux", "python", "lua", "php", "html5", "c", "nosql"], "history": ["chinese history", "global history"], "SF": [ "hard SF", "Thought experiment" ], "music": [ "New Age", "Chinese old theme", "Electronic music", "Strange Music :}"] } } |
|
From: Guenter M. <mi...@us...> - 2011-05-05 07:23:28
|
On 2011-05-04, Yunfan Jiang wrote: > hi, > i got some knowledges here > http://docutils.sourceforge.net/docs/howto/rst-directives.html while i > am looking for the documents for developer Did you find the developer docs in the http://docutils.sourceforge.net/docs/dev/ directory, too? > i am doing my own blog system which use rst as the main format, > currently my target is to use a single rst file to contains all the > field that a blog entry needs, like title, tags, uri_code, and content, > and i want to store the title, tags, and uri_code in the file's > FieldList like this >:title: the first blog of mine >:uri_code: the-first-blog >:tags: test python about > here is content > but the problem is i dont know how to parsing a reSturctured text and > got the target field's value , there's so many documents that tolds how > to translate from rst to another format ( html, xml, ...), could you > show me same documents about this target, or could you give me some > sample? This depends on what exactly you want to achieve. In any case you might need to look at the source (in addition to the developers documentation). a) do you implement a "blog-writer" and want to use the field values in them? -> have a look at html4css1/__init__.py or latex2e/__init__.py to see how special field names are detected (hint: look at the visit_docinfo() and visit_field_name() definitions). b) do you want to parse the rst source separtely? -> convert to XML and use standard tools to extract the info, or convert to a Docutils doctree and extract the info traversing the tree (similar to what is done in the transforms -> see docutils/docutils/transforms/*.py). Günter |
