[sphinx-dev] EPUB Output improvements
It would be nice to have support for dc:date in the OPF metadata and a cover. Both of these are implemented in the EpubBuilder sub class here: http://bazaar.launchpad.net/~kovid/calibre/trunk/annotate/head:/src/calibre/manual/epub.py Unfortunately I don't have the time to create a patch against epub.py in the sphinx trunk, hence the hackish subclassing -- 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: lilypond extension
Hi Federico, It looks like lilypond failed at some stage. Try to run the following commands (Linux or MacOS): $ mkdir out $ echo \relative c'' {c4 a d c} music.ly $ lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts -o out --png music.ly You will have a file `out/music.png` which you will be able to view. If this doesn't work I would blame the lilypond installation. In my case I'm on a MacOS X and since I installed lilypond as a macos package I have to point to the lilypond executable from the config.py file like this: pnglily_lilypond = '/Applications/LilyPond.app/Contents/Resources/bin/lilypond' You can also contact the author of the lilypond extension Wei-Wei Guo at wwgu...@gmail.com On Sun, Jul 25, 2010 at 5:00 PM, Federico Bruni fedel...@gmail.com wrote: Ok, I managed to make the extension work (stupid me, I put two extensions = ). But now the extension seems to have a problem. It creates the .ly file in /tmp but the .png is not created so the build fails. Please find the log attached. I guess this (from the README in lilypond extension) is optional: Installing == - A new config 'pnglily_fontsize', which can be used to set fontsize of 'lily' role and 'lily' directive. :: pnglily_fontsize = ['6', '-3'] The first value is for 'lily' role setting in absolute fontsize. The second value is for 'lily' directive setting in relative fontsize. I wonder: why putting it in Installing section? Maybe is it required? I've tried to put in conf.py: pnglily_fontsize = ['6', '-3'] But I get the same errors. Cheers, Federico Il giorno dom, 25/07/2010 alle 22.36 +0200, Federico Bruni ha scritto: I've realized that the lilypond.py file found in the mailing list was not enough. I've downloaded the complete package of lilypond-1.0 here: http://bitbucket.org/birkenfeld/sphinx-contrib/downloads I've also changed the path in conf.py: sys.path.append(os.path.abspath('exts/lilypond/sphinxcontrib')) extensions = ['lilypond'] But again lilypond code is not rendered and I get a warning which says: (ERROR/3) Unknown directive type lily I attach the very simple file I'm trying to process. Maybe there's some synthax error? Any hint appreciated. Thanks, Federico Il giorno dom, 25/07/2010 alle 07.24 -0700, Federico Bruni ha scritto: Hi all, I'm a brand new Sphinx user (really impressed by your software). I'm planning to write a tutorial about LilyPond (http://lilypond.org/) and I've found out that last year a specific extension for LilyPond was written: http://groups.google.com/group/sphinx-dev/browse_thread/thread/e6fb63b23a539714/0dde66d7970d7e5d?lnk=gstq=lilypond#0dde66d7970d7e5d I'm trying to use it, but it's not working. Here's what 've done: * started a project with sphinx-quickstart * added file lilypond.py (taken from thread above) in the subdrectory 'lily' in the root dir of my project * added these line in conf.py: sys.path.append(os.path.abspath('lily')) extensions = ['lilypond'] Then I add a lilypond snippet in a .rst file: .. lily:: \relative c'' { c4 a d c } When I compile with 'make html' I get this error: (ERROR/3) Unknown directive type lily. What I'm missing? Thanks in advance for your help. Regards, Federico -- 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. -- Vadim Gubergrits -- 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] citations / references as numbers
How to get the citations / references look like [number] ? The number- inside-square-brackets [1], [2], ... is the typical LaTeX look one gets from \cite{LABEL}, and how i think is the common way to typeset citations in scientific articles or technical reports. However, from Sphinx, both the HTML and PDF output i have obtained looks like [LABEL] where the label-name is written out. The [number] would not be mixed with the footnotes in the PDF output, as the footnotes will be small-font-superscripts compared to the citations with square brackets and normal font. I see that it would be possible to filter/scan the *.tex output files and insert \cite. Or maybe there are already some nice add-on available ? Otherwise, i would wish to have a Sphinx/restructured text syntax that handles this, e.g. with the #-character _after_ the label: This is a reference to document [LABEL#]_ and intended NOT to be a footnote ... .. [LABEL#] A. Adams, Scientific American, . Can you please tell if some solution to this can be obtained in Sphinx ? Thanks/ Peo -- 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] Creating a custom directive: trials and tribulations
I'm attempting to create a custom reST directive, which returns a tree of `containers`, two of which contain a `LiteralInclude` directive. Here's the code for my extension module: class AsmFileDirective(rst.Directive): required_arguments = 1 optional_arguments = 0 has_content = False def run(self): reference = self.arguments[0] sourceandoutput = nodes.container(classes=[sourceandoutput]) source = nodes.container(classes=[source]) source_header = nodes.container(classes=[header]) source_header.append(nodes.Text(reference + .nasm)) source.append(source_header) source.append(LiteralInclude( name = self.name, arguments = [code/ + reference + /prog.nasm], options = self.options, content = self.content, lineno = self.lineno, content_offset = self.content_offset, block_text = self.block_text, state = self.state, state_machine = self.state_machine )) output = nodes.container(classes=[source]) output_header = nodes.container(classes=[header]) filename = nodes.container(classes=[filename]) filename.append(nodes.Text(./ + reference)) output_header.append(filename) output.append(output_header) sourceandoutput.append(source) sourceandoutput.append(output) return [sourceandoutput] def setup(app): app.add_directive(asmfile, AsmFileDirective) I have two (and possibly more) problems with this: (ERROR THE FIRST) When a `container` is written as html, I get the error: Exception occurred: File /usr/local/lib/python2.6/dist-packages/docutils-0.6-py2.6.egg/ docutils/writers/html4css1/__init__.py, line 362, in starttag classes.append(atts['class']) AttributeError: 'str' object has no attribute 'append' So for some reason, the array that I'm passing in is getting converted to a string ? When I instead pass in a string, I get the same error, obviously. (ERROR THE SECOND) the arguments for instantiating a LiteralInclude are horrendous, and I can't even identify the problems I'm having with that. -- 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] Re: Creating a custom directive: trials and tribulations
To clarify, this is the end result that I want. The following: .. asmfile:: cat will get expanded into the equivalent of: .. container:: sourceandoutput .. container:: source .. container:: header cat.nasm .. literalinclude:: /code/cat/clip.nasm .. container:: output .. container:: header .. container:: filename ./cat .. container:: arguments .. literalinclude:: /code/cat/args.txt :language: none .. literalinclude:: /code/cat/output.txt :language: none Basically, I pass in an identifier for a directory which contains (1) source code, and (2) the output from running it. With appropriate CSS, I then get a pretty side-by-side comparison. Best James On Wed, Jul 28, 2010 at 5:13 PM, eegg jameshfis...@gmail.com wrote: I'm attempting to create a custom reST directive, which returns a tree of `containers`, two of which contain a `LiteralInclude` directive. Here's the code for my extension module: class AsmFileDirective(rst.Directive): required_arguments = 1 optional_arguments = 0 has_content = False def run(self): reference = self.arguments[0] sourceandoutput = nodes.container(classes=[sourceandoutput]) source = nodes.container(classes=[source]) source_header = nodes.container(classes=[header]) source_header.append(nodes.Text(reference + .nasm)) source.append(source_header) source.append(LiteralInclude( name = self.name, arguments = [code/ + reference + /prog.nasm], options = self.options, content = self.content, lineno = self.lineno, content_offset = self.content_offset, block_text = self.block_text, state = self.state, state_machine = self.state_machine )) output = nodes.container(classes=[source]) output_header = nodes.container(classes=[header]) filename = nodes.container(classes=[filename]) filename.append(nodes.Text(./ + reference)) output_header.append(filename) output.append(output_header) sourceandoutput.append(source) sourceandoutput.append(output) return [sourceandoutput] def setup(app): app.add_directive(asmfile, AsmFileDirective) I have two (and possibly more) problems with this: (ERROR THE FIRST) When a `container` is written as html, I get the error: Exception occurred: File /usr/local/lib/python2.6/dist-packages/docutils-0.6-py2.6.egg/ docutils/writers/html4css1/__init__.py, line 362, in starttag classes.append(atts['class']) AttributeError: 'str' object has no attribute 'append' So for some reason, the array that I'm passing in is getting converted to a string ? When I instead pass in a string, I get the same error, obviously. (ERROR THE SECOND) the arguments for instantiating a LiteralInclude are horrendous, and I can't even identify the problems I'm having with that. -- 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] Sphinx doc and sphinxsearch
Hi there! Kind of silly question. Does Sphinx - documentation generator has anything to do with Sphinx - free open-source SQL full-text search engine? I'm asking about any possible similarities or any common things/people behind those two. Regards PS. I see quite similar logo ;) -- 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] Sphinx doc and sphinxsearch
The only similarity is the name and may be the similar logo as you pointed out. -- 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] Re: citations / references as numbers
By the way, can the bibliographic fields be used to get citation / reference as number, inside brackets, e.g. [1] etc. ? I m a beginner to Sphinx - i suppose you experienced can give advice. I would be very surprised if i m the only one who would like to see referencing / citations type set as is standard in many places. Thanks On Jul 28, 3:16 pm, peo peteroliv...@gmail.com wrote: How to get the citations / references look like [number] ? The number- inside-square-brackets [1], [2], ... is the typical LaTeX look one gets from \cite{LABEL}, and how i think is the common way to typeset citations in scientific articles or technical reports. However, from Sphinx, both the HTML and PDF output i have obtained looks like [LABEL] where the label-name is written out. The [number] would not be mixed with the footnotes in the PDF output, as the footnotes will be small-font-superscripts compared to the citations with square brackets and normal font. I see that it would be possible to filter/scan the *.tex output files and insert \cite. Or maybe there are already some nice add-on available ? Otherwise, i would wish to have a Sphinx/restructured text syntax that handles this, e.g. with the #-character _after_ the label: This is a reference to document [LABEL#]_ and intended NOT to be a footnote ... .. [LABEL#] A. Adams, Scientific American, . Can you please tell if some solution to this can be obtained in Sphinx ? Thanks/ Peo -- 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] How to use intersphinx to link to sphinx or python documentation
Hi, I just started using sphinx 1.0 for our documentation and I'm having trouble using the intersphinx extension. I added python and sphinx itself in conf.py: intersphinx_mapping = { 'python': ('http://docs.python.org/', None), 'sphinx': ('http://sphinx.pocoo.org', None) } And now I try to link to these documentations. But even this example from the sphinx documentation does not work: :ref:`comparison manual python:comparisons` (It will just output python:comparisons in italics without a link). Also, I don't get how I would know about these labels anyway (for documentation I didn't write): When I have to look at the python or sphinx documentation source to find the labels first, it's way faster to just link the URL like `this http://sphinx.pocoo.org/markup/ inline.html#ref-role`_, isnt it? Thanks for your help, Chris -- 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] Projects using sphinx: PyTango and tau
Hello, I would like to add PyTango and tau to the list of projects that gladdly use sphinx. The links are respectively: PyTango: http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html -- 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: lilypond extension
Il giorno mer, 28/07/2010 alle 00.01 -0400, Vadim Gubergrits ha scritto: Hi Federico, It looks like lilypond failed at some stage. Try to run the following commands (Linux or MacOS): $ mkdir out $ echo \relative c'' {c4 a d c} music.ly $ lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts -o out --png music.ly You will have a file `out/music.png` which you will be able to view. If this doesn't work I would blame the lilypond installation. Thanks Vadim, I've found that command in lilypond.py, so I'm starting to figure out what's happening. I think the problem is that the command is not correct. If you check the LilyPond documentation (either 2.12 or 2.13) you can read: -o,--output=FILE Set the default output file to FILE. The appropriate suffix will be added (e.g. .pdf for pdf So -o specifies a file, not a directory. Am I missing something? If you use lilypond-book instead of lilypond, you can use -o as output directory. Maybe lilypond-book could be a better tool for writing music documentation, as its aim is integrating text and music. For example, lilypond documentation is compiled using lilypond-book and texinfo. You can also contact the author of the lilypond extension Wei-Wei Guo at wwgu...@gmail.com Thanks! I put him in CC, just in case he's not subscribed to the list. I've tried to change this line in lilypond.py: lilypond_args += ['-dbackend=eps', '-dno-gs-load-fonts', '-dinclude-eps-fonts', # '-o', tempdir, '--png'] to something like: lilypond_args += ['--png', '-dpreview'] which works fine in a terminal, but not in sphinx. The extension requires the temporary directory: '-o', tempdir Unfortunately, lilypond seems to need the path of a file. Should I substitute tempdir with something else? I'm not a developer so I beg your pardon in advance in case I said too much stupid things :) Regards, Federico -- 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] Python3 support in Sphinx trunk
Hello Sphinx Users, Developers and Fans, Today we added support for Python 3.x to Sphinx and we would like to invite you to test it, to play around with it and to see if it works with your existing Python 3.x projects. In order to install it locally we recommend using virtualenv3 or virtualenv5 (I tested it with the latter) which allows you to cleanly install dependencies for development or if you simply if you want to test a Python application without changing the global environment. To clone the repository you also need Mercurial, the DVCS we use for development. First of all you cd into a directory and clone the repo, the result should look like this. ~# cd Projects Projects# hg clone http://bitbucket.org/birkenfeld/sphinx destination directory: sphinx requesting all changes adding changesets adding manifests adding file changes added 2501 changesets with 8773 changes to 1513 files updating to branch default 391 files updated, 0 files merged, 0 files removed, 0 files unresolved Then we cd into the directory and create the virtualenv, make sure that virtualenv uses python3 for the env, once it's created we can activate it: Projects# cd sphinx sphinx# virtualenv5 env New python executable in env/bin/python3.1 Also creating executable in env/bin/python Installing setuptoolsdone. sphinx# source env/bin/activate (env)sphinx# Once it's activated you will notice the (env) at the beginning of the prompt, now we can install the dependencies: (env)sphinx# easy_install docutils pygments jinja2 install_dir /home/dasich/Projects/sphinx/env/lib64/python3.1/site-packages/ Searching for docutils Reading http://pypi.python.org/simple/docutils/ Reading http://docutils.sourceforge.net/ Best match: docutils 0.7 Downloading http://pypi.python.org/packages/source/d/docutils/docutils-0.7.tar.gz#md5=9aec716baf15d06b5aa57cf8d5591c15 Processing docutils-0.7.tar.gz Running docutils-0.7/setup.py -q bdist_egg --dist-dir /tmp/easy_install-cpiGhF/docutils-0.7/egg-dist-tmp-e1oOBJ roman module already present; ignoring extras/roman.py. warning: no files found matching 'MANIFEST' warning: no previously-included files matching '.cvsignore' found under directory '*' warning: no previously-included files matching '*.pyc' found under directory '*' warning: no previously-included files matching '*~' found under directory '*' warning: no previously-included files matching '.DS_Store' found under directory '*' copying aux dirs zip_safe flag not set; analyzing archive contents... docutils.writers.pep_html.__init__: module references __file__ docutils.writers.odf_odt.__init__: module references __file__ docutils.writers.s5_html.__init__: module references __file__ docutils.writers.latex2e.__init__: module references __file__ docutils.writers.newlatex2e.__init__: module references __file__ docutils.writers.html4css1.__init__: module references __file__ docutils.parsers.rst.directives.misc: module references __file__ tools.dev.profile_docutils: module references __file__ test.DocutilsTestSupport: module references __file__ test.DocutilsTestSupport: module MAY be using inspect.getouterframes test.test_language: module references __path__ test.alltests: module references __file__ test.test_readers.__init__: module references __file__ test.test_readers.test_python.__init__: module references __file__ test.test_readers.test_pep.__init__: module references __file__ test.test_parsers.__init__: module references __file__ test.test_parsers.test_rst.__init__: module references __file__ test.test_parsers.test_rst.test_directives.__init__: module references __file__ test.test_parsers.test_rst.test_directives.test_include: module references __file__ test.test_writers.__init__: module references __file__ test.test_transforms.__init__: module references __file__ Adding docutils 0.7 to easy-install.pth file Installing rst2newlatex.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2html.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2odt_prepstyles.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2s5.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2man.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2latex.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2xml.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2pseudoxml.py script to /home/dasich/Projects/sphinx/env/bin Installing rst2odt.py script to /home/dasich/Projects/sphinx/env/bin Installing rstpep2html.py script to /home/dasich/Projects/sphinx/env/bin Installed /home/dasich/Projects/sphinx/env/lib/python3.1/site-packages/docutils-0.7-py3.1.egg Processing dependencies for
Re: [sphinx-dev] How to use intersphinx to link to sphinx or python documentation
On Wed, Jul 28, 2010 at 5:47 AM, Christoph Neuroth christoph.neur...@googlemail.com wrote: Hi, Howdy! I just started using sphinx 1.0 for our documentation and I'm having trouble using the intersphinx extension. I added python and sphinx itself in conf.py: intersphinx_mapping = { 'python': ('http://docs.python.org/', None), 'sphinx': ('http://sphinx.pocoo.org', None) } And now I try to link to these documentations. But even this example from the sphinx documentation does not work: :ref:`comparison manual python:comparisons` (It will just output python:comparisons in italics without a link). Did you also add intersphinx to the extensions value in your conf.py? Also, I don't get how I would know about these labels anyway (for documentation I didn't write): When I have to look at the python or sphinx documentation source to find the labels first, it's way faster to just link the URL like `this http://sphinx.pocoo.org/markup/ inline.html#ref-rolehttp://sphinx.pocoo.org/markup/%0Ainline.html#ref-role`_, isnt it? It might indeed be faster to link to the exact URL as you suggest, but the advantage intersphinx provides that it gives you a way to link to a specific label in the other documentation - even if it moves. So if someone rearranges their docs, you just have to run a full rebuild of your docs (to get the latest objects.inv files downloaded), and it should fix any broken links you might have. (Of course you need intersphinx to actually _work_ first ;) ) Thanks for your help, Chris Good luck! Kevin Horn -- 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] How to use intersphinx to link to sphinx or python documentation
I'm having trouble using the intersphinx extension. I added python and sphinx itself in conf.py: intersphinx_mapping = { 'python': ('http://docs.python.org/', None), 'sphinx': ('http://sphinx.pocoo.org', None) } Did you also add 'sphinx.extensions.intersphinx' to the `extensions` in the conf.py? And now I try to link to these documentations. But even this example from the sphinx documentation does not work: :ref:`comparison manual python:comparisons` (It will just output python:comparisons in italics without a link). As expected if intersphinx is not loaded as described above. Also, I don't get how I would know about these labels anyway (for documentation I didn't write): When I have to look at the python or sphinx documentation source to find the labels first, it's way faster to just link the URL like `this http://sphinx.pocoo.org/markup/ inline.html#ref-role`_, isnt it? You won't know about the labels unless you read about the source of the documentation of the project you are referencing. The real advantage of intersphinx is that if you write :py:meth`dict.pop` in your documentation with intersphinx this will generate a link to the documentation of the dict.pop method which should be somewhere on docs.python.org. If the location on docs.python.org changes you only have to rebuild your documentation. A lot of projects use Sphinx especially in the web area where this is very helpful. Obviously the usage of intersphinx requires will make the compiling a bit slower but the question is how slow? I don't think it will be more than a second if it is that much at all for most projects and it's not necessary to build the entire documentation every time anyway, not to mention that this is not something you do that often. -- 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.