Re: [sphinx-dev] How to override values in conf.py by values read from a Settings.yml (YAML) file?
2012/7/23 Martin Bless m.bl...@gmx.de: Hello everybody, maybe there is an obvious solution - but I just don't see it. At the end of 'conf.py' I want to read and parse an additional 'Settings.yml' configuration file and add those settings to what we already have in 'conf.py'. If present settings from the YAML file should take precedence. So I need a way to programmatically define settings like those in the lines of conf.py. For example: html_theme = 'sphinx' So what I need is something like this: ## conf.py: # ... # normal settings ... # ... more = parse_yaml() # return a dictionary for k in more.keys(): # now I'd like to add ((k)) = more[k] # where ((k)) should be a variable in the conf.py namespace. Q: How do I do that? Quick and dirty: globals().update(read_my_dict_from_yaml()) Alternativel you can update the settings after Sphinx has parsed conf.py: def setup(app): for key, value in read_my_dict_from_yaml(): setattr(app.config, key, value) In other words: If in conf.py there is: html_theme = 'sphinx' k = 'html_theme' v = 'basictheme' Q: How do I write `k` = v? globals()[k] = v In other words: Q: How do I access the dictionary in conf.py that dir() queries? Use globals() within conf.py. globals() returns all names on module level, and the settings in conf.py are module-level names. I just found that this seems to work: html_theme = 'sphinx' k = 'html_theme' v = 'basictheme' L = locals() L[k] = v print html_theme # - gives 'basictheme' Q: Is that the right and best way to do this? It works accidentally, because on module level locals() is equivalent to globals(). However, according to the documentation locals() returns a *independent* dictionary. Modifications to this dictionary are not guaranteed to propagate to the corresponding namespace. As said above, use globals(). -- 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.
Re: [sphinx-dev] autodoc and module variables
Am 16. März 2012 11:34 schrieb Andrea Crotti andrea.crott...@gmail.com: On 03/16/2012 10:31 AM, Daniel Neuhäuser wrote: A colon has to follow the hash like #: so in order for Sphinx to pick it up as a doc string for that attribute. Ah great thanks, just to check, is it written anywhere? Because it's not really trivial unless one knows it already.. http://sphinx.pocoo.org/ext/autodoc.html#directive-autodata -- 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.
Re: [sphinx-dev] sphinx-build and outdir
Am 14. März 2012 06:17 schrieb Andrea Crotti andrea.crott...@gmail.com: I'm having some troubles understanding the wonders of sphinx-build.. So in mailman 3 we have a perfectly working python setup.py build_sphinx, that reads the setup.cfg file with the following: [upload_docs] upload_dir: build/sphinx/html we would like, however to get spinx-build working by itself, but for example on readthedocs.org there is no way to pass manually the outdir. Why do you want to configure the output directory on readthedocs.org?! There is no need to do so, readthedocs.org gets things right by itself. Is there no way to set the default outdir in the conf.py file? No. And if no maybe I should do something different? Obviously. -- 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.
Re: [sphinx-dev] Feature Flags in Sphinx documentation
2011/9/20 ashwin rashwi...@gmail.com: Hi All, I have a requirement in which I need to do the following: a. Generate documentation for different set of products. b. For all these products, there would be only one set of REST files. c. We want to have a feature flag in these REST files. This is required so that, based on the feature flag(or product) for which we want the documentation, we want the REST files to be compiled for that specific product. This feature flag is required to control the display of output per platform. Internally in the REST files, for these feature flags, we may include/ exclude certain pieces of documentation, or change the limits for different products etc. These feature flags in a way, should work similar to the C macros. I have searched through the Sphinx directives and am unable to find anything which matches this requirement. So, just wanted to check, if I have missed anything here? Or should a new directive be added for this purpose? Any pointers in this regard would be very helpful, since I am stuck on this, for my project. You may want to look at the .. only:: directive [1]. [1] http://sphinx.pocoo.org/markup/misc.html#including-content-based-on-tags -- 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.
Re: [sphinx-dev] autodoc: keeping names of contants in signature
2011/8/31 Sebastian Rahlf ba...@rotekroete.de: Hi! I'm using Sphinx's autodoc feature to document my API. For example:: DEFAULT_OPTION = 'default' def do_something(msg, option=DEFAULT_OPTION): print msg The generated documentation now shows the following signature: do_something(msg, option='default') How can I tell Sphinx to keep the name of the constant value? Most likely you can't. Python evaluates DEFAULT_OPTION during import, thus the constant is long gone when Sphinx looks at the *imported* module to extract documentation from it. If at all possible, I'd like NOT to write all signature by hand again. Seems to be the only way. I feared as much. Thanks for the info though. You may want to report this as issue to the Sphinx issue tracker. Iirc Sphinx parses the source code itself, too, to extract documentation for simple module and class attributes. This could probably be used to use the original function signatures, too, so the Sphinx devs can probably easily add this feature. -- 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.
Re: [sphinx-dev] autodoc: keeping names of contants in signature
2011/8/30 Sebastian Rahlf ba...@rotekroete.de: Hi! I'm using Sphinx's autodoc feature to document my API. For example:: DEFAULT_OPTION = 'default' def do_something(msg, option=DEFAULT_OPTION): print msg The generated documentation now shows the following signature: do_something(msg, option='default') How can I tell Sphinx to keep the name of the constant value? Most likely you can't. Python evaluates DEFAULT_OPTION during import, thus the constant is long gone when Sphinx looks at the *imported* module to extract documentation from it. If at all possible, I'd like NOT to write all signature by hand again. Seems to be the only way. -- 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.
Re: [sphinx-dev] Persistent storage and conditional rebuild in extensions
2010/8/17 Matt Williams li...@milliams.com:
While parts of this can obviously be done with plain Python, I was
wondering how it should be done within the framework of Sphinx. This
is particularly needed in order to re-evaluate the roles when the file
has changed.
Just attach your cache to the environment object app.env:
def init_doxylink(app):
tag_file_mtime = os.path.getmtime(tagfile)
if not hasattr(app.env, 'doxylink_cache'):
# no cache present, initialize it
app.env.doxylink_cache = DoxyLinkCache(tag_file_mtime)
elif tag_file_mtime app.env.doxylink_cache.tag_file_mtime:
# tag file has been modified since cache creation
app.env.doxylink_cache = DoxyLinkCache(tag_file_mtime)
def setup(app):
app.connect('builder-inited', init_doxylink)
Sphinx pickles the whole environment object, so you get caching for
free for any object attached to the environment. You just need to
create the cache, in case sphinx has a fresh environment (e.g. built
after configuration changes, make clean or so), and to verify, if
the cache is up to date. This is done in init_doxylink(), which is
run, when the builder is initialized. This is what
sphinx.ext.interspinx does.
Of course, all access to the tag files must be done through the cache.
How the cache could be implemented, depends on the way your extension
works. collections.defaultdict generally makes a nice base class for
caches. You could for instance use signatures as keys, normalize them
internally, and re-implement __missing__ to look the signature up in
the cache file:
class DoxyLinkCache(collections.defaultdict):
def __getitem__(self, signature):
return collections.defaultdict.__getitem__(self, normalize(signature))
def __missing__(self, signature):
# look up normalized signature in the tag file
HTH
Sebastian Wiesner
--
You received this message because you are subscribed to the Google Groups
sphinx-dev group.
To post to this group, send email to sphinx-...@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.
[sphinx-dev] 3rd party extensions
Hi, http://bitbucket.org/birkenfeld/sphinx-contrib seems to be kind of semi-official third-party extension repository for Sphinx, some extensions developed in this repository are also released on PyPI as sphinxcontrib-*. However, this repository is neither mentioned in the Sphinx documentation [1] nor in the Sphinx wiki [2]. I'd guess, that many users miss potentially useful extensions, because they simply don't know this repository, I personally only accidentally stumbled over this repository and wouldn't have known it otherwise. Shouldn't this repository be mentioned in the Sphinx documentation or at least in the Sphinx wiki? Sebastian [1] http://sphinx.pocoo.org/latest/extensions.html#third-party-extensions [2] http://bitbucket.org/birkenfeld/sphinx/wiki/Home -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@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.
Re: [sphinx-dev] Re: A set of extensions for sphinx
On Thursday 15 April 2010 00:23:32 Tim Michelsen wrote - lunar.sphinx.ext.issuetracker: Link issue references like #10 to the issue trackers in GitHub or BitBucket. What to you think about Launchpad, Sourceforge and Google Code? No objections, I'm just not using any of these services and had no personal need therefore. But I'll add these, if they provide a proper API, it's not too difficult. Patches are also welcome ;) -- Freedom is always the freedom of dissenters. (Rosa Luxemburg) signature.asc Description: This is a digitally signed message part.
Re: [sphinx-dev] Re: A set of extensions for sphinx
On Friday 16 April 2010 11:52:11 Sebastian Wiesner wrote On Thursday 15 April 2010 00:23:32 Tim Michelsen wrote - lunar.sphinx.ext.issuetracker: Link issue references like #10 to the issue trackers in GitHub or BitBucket. What to you think about Launchpad, Sourceforge and Google Code? I've added Launchpad and Google Code in latest tip. Sourceforge is still missing, for I a quick search did not reveal any web service API to access data on source forge, and I'm currently not in the right mood to dig into the sourceforge HTML to scrape issue data from the website. -- Freedom is always the freedom of dissenters. (Rosa Luxemburg) signature.asc Description: This is a digitally signed message part.
[sphinx-dev] A set of extensions for sphinx
Hi, I've written a couple of extensions for Sphinx, that you may or may not find useful: - lunar.sphinx.ext.programoutput: Include the output of programs into documentation - lunar.sphinx.ext.ansi: Parse ANSI color sequences in program output and color HTML output - lunar.sphinx.ext.issuetracker: Link issue references like #10 to the issue trackers in GitHub or BitBucket. - lunar.sphinx.ext.epydoc: Cross-reference epydoc-generated API docs These extensions are written and tested against the current tip of the sphinx- domains [1] branch. They are available in the Python Package Index [2], the sources are hosted on BitBucket [3]. A bit of documentation is also available [4]. [1] https://bitbucket.org/birkenfeld/sphinx-domains/ [2] http://pypi.python.org/pypi/lunar.sphinx.ext/ [3] https://bitbucket.org/lunar/lunar.sphinx.ext/ [4] http://packages.python.org/lunar.sphinx.ext/ -- Freedom is always the freedom of dissenters. (Rosa Luxemburg) signature.asc Description: This is a digitally signed message part.
[sphinx-dev] Re: Three sphinx questions
At Tuesday 25 August 2009 00:58:06
2) How can I sort members using autodoc in the order they were
defined?
autodoc imports the module and analyzes its namespace, which is an unordered
dictionary. The order of definition cannot be restored from this dictionary.
You have to discard the :members: option and order members for yourself:
.. autoclass:: Spam
.. autoattribute:: number_of_eggs
.. automethod:: some_eggs
.. automethod:: some_more_eggs
3) How can I avoid sphinx to add parameter information to specific
classes using autodoc?
If parameter information refers to the signature of the constructor, you
have two ways:
1. Override the signature:
.. autoclass:: Spam(first_arg, second_arg)
2. Connect a function to the autodoc-process-signature [1] signal by adding
something like this to your conf.py:
def process_signature(app, what, name, obj, opts, sig, ann):
if what == 'class':
return (('spam', ),)
def setup(app):
app.connect('autodoc-process-signature', process_signature)
This will change the signature of all classes documented by autodoc to contain
only one argument called spam.
4) I have some dummy class named FOO. I'm using that class within
parameter definitions, and the output I get using autodoc is the
standard FOO at . stuff I don't want to see. How can I
overwrite this? Overwriting the __repr__ or __str__ methods doesn't
change that thing.
Use a signature processing function like describe above to remove or change
this FOO parameter. The original signature is available in the signature
argument of this function.
[1] http://sphinx.pocoo.org/ext/autodoc.html#event-autodoc-process-signature
--
Freedom is always the freedom of dissenters.
(Rosa Luxemburg)
signature.asc
Description: This is a digitally signed message part.
Re: Sphinx for general use
Sunday 09 November 2008 20:32:58 Georg Brandl Hans Fangohr schrieb: Dear all, Alaric Haag schrieb: Hello, The Sphinx page bills it as a tool for documenting Python projects. I perceive it to be more of a document management tool that uses ReST. I've barely scratched the surface of using it though. So, I'm considering using it to make a lab manual to document all sorts of things we do, mostly NOT related to Python. I like the idea that one document can serve both as an on-line resource, and as a printed book. What, if anything, ties Sphinx to documenting Python projects, or does it just _facilitate_ that? As Sebastian said, Python is its origin and focus, but there's nothing that prevents you from not documenting something Python. q§ Just to add my bit: I am considering to use Sphinx for setting up a web-page that is not documenting a software project or code, but rather represents some more generic kind of webpage (for example for a research group). I have played with rest2www before (and use this for http://www.soton.ac.uk/~fangohr for example), and am currently trying to understand what I can and can't do with sphinx for these kind of applications. (All I need are static webpages, so I didn't go down the Django route yet). If people can recommend any other tools that are similar to rest2www and 'sphinx for generic webpages', I'd be interested about that. I know of one generic personal webpage that's made with Sphinx: http://lunaryorn.de/ FWIW, the Sphinx 0.5 sources of the site are available online at http://git.lunaryorn.de/?p=lunarsite;a=summary Hih -- Freedom is always the freedom of dissenters. (Rosa Luxemburg) signature.asc Description: This is a digitally signed message part.
