[sphinx-dev] EPUB Output improvements

2010-07-28 Thread Kovid
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

2010-07-28 Thread Vadim Gubergrits
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

2010-07-28 Thread peo
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

2010-07-28 Thread eegg
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

2010-07-28 Thread James Fisher
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

2010-07-28 Thread slafs
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

2010-07-28 Thread DasIch
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

2010-07-28 Thread peo
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

2010-07-28 Thread Christoph Neuroth
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

2010-07-28 Thread coutinhotiago
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

2010-07-28 Thread Federico Bruni
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

2010-07-28 Thread DasIch
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

2010-07-28 Thread Kevin Horn
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

2010-07-28 Thread DasIch
 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.