from:"TP"

On Thu, Jan 13, 2011 at 9:35 AM, Curiouslearn curiousle...@gmail.com wrote:
 @TP  Thanks! If you don't mind, can you send me an example of your
 subtitle css. Also, did you save it in _static.

in my conf.py file I have:
html_theme = 'customtheme'

html_theme_path = ['.']

in my customtheme\static\customtheme.css_t file i have (along with a
bunch of other stuff):

@import url(default.css);
div.container.subtitle {
  font-size: 160%;
  font-family: sans-serif;
  font-weight: normal;
  margin-bottom: 0.5em;
}

(This makes sure that *only* div's that have both container 
subtitle class names will be affected)

Does one need both
 container and class directives to do this?

Given the following in a .rst file:

.. container::
   :class: subtitle

container is the standard docutils directive documented at
http://docutils.sourceforge.net/docs/ref/rst/directives.html#container.
:class:  is an option for that directive. It generates something
like the following HTML:

div class=class subtitle container
This is My Very Long Subtitle span class=raw-htmlbr //span
That Spans Two Lines By Using a lt;br /gt;
/div

After rereading the above mentioned documentation on container, I
see that I should probably have done the following:

.. container:: subtitle

Which generates the clearer:

div class=subtitle container

 Thanks for your patience.


 On Thu, Jan 13, 2011 at 7:28 AM, TP wing...@gmail.com wrote:
 On Thu, Jan 13, 2011 at 2:07 AM, Curiouslearn curiousle...@gmail.com wrote:
 I was also wondering about exactly the same thing yesterday. I, in
 fact, sent an email to the group but did not see that email reach the
 group.

 Anyhow, is it possible to increase the text size in addition to using
 strong emphasis?

 Thanks.

 On Thu, Jan 13, 2011 at 2:34 AM, Georg Brandl ge...@python.org wrote:
 -BEGIN PGP SIGNED MESSAGE-
 Hash: SHA1

 Am 12.01.2011 22:21, schrieb Kevin Cole:
 Hi,

 I haven't been fooling w/ Sphinx or reST very long, and don't know LaTeX. 
  I'm
 currently running Sphinx 1.0.1 under Ubuntu Maverick.

 I've tried a few different ways to get a document subtitle, but in LaTeX, 
 it
 interprets the subtitle as a section heading. Not what I want at all.  
 Ideally,
 I'd want a line of text in a large font, followed immediately by text in a
 smaller font.  But I could probably live w/ two lines of equally large 
 fonts.

 Hi Kevin,

 it's not possible with either rST or LaTeX to break a title in two lines.

 What you could do is to just use strong emphasis:


 Title
 =

 **Subtitle**


 Georg

 --
 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.



 For HTML generation, I did something like this by doing:

    ===
    My Normal Title
    ===

    .. container::
       :class: subtitle

       This is My Very Long Subtitle |BR| That Spans Two Lines
       By Using a br /

    .. |BR| replace:: :raw-html:`br /`

 and creating a custom CSS style for my new subtitle class to make
 its font larger than normal. Maybe you can do something similar for
 LaTeX?

 --
 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.



 --
 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.



-- 
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] how to share documents created using Sphinx (html version)

On Thu, Jan 13, 2011 at 11:18 AM, Curiouslearn curiousle...@gmail.com wrote:
 Hello All,

 Two questions about sharing Sphinx documentation with others:

 (1) Do you know of an easy way of private hosting of Sphinx documents
 online (where you can restrict access to it)? Is there a web host or
 some solution that makes this possible easily?

 (2) If I want to email the documentation to someone, which files do I
 need to email? Do I need to send _build, _template and _static
 directories. Does the recipient need to have Python?

 Thanks,
 Bharat

 --
 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.



All you have to do is copy the contents of the _build/html directory
tree to your web host or email it to someone (You can skip the
.buildinfo  objects.inv files if you want). The _static directory is
automatically copied to _build/html/_static as are the processed
template files (.css_t files get converted to .css files).

It's up to your website configuration as to whether those pages are
private or not.

Recipients only need a web browser to view Sphinx generated HTML pages.

-- 
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] Two newbie questions

On Thu, Jan 13, 2011 at 9:32 AM, Curiouslearn curiousle...@gmail.com wrote:
 @Federico: Thanks so much. This is great.

 @Daslch: Thanks. Do I just save my css file in the _static directory
 and then invoke the styles I define there using raw html directive.

 Thanks again.

Here's what I do. In my conf.py file I set:

html_theme = 'customtheme'

html_theme_path = ['.']

rst_prolog=
.. role:: myrole
   :class: mycustomrole


My customtheme\theme.conf contains:

[theme]
inherit = default
stylesheet = customtheme.css
pygments_style = sphinx

and customtheme\static\customtheme.css_t contains:

@import url(default.css);
.mycustomrole {
  font-family: monospace;
  font-size: 125%;
}

if for example I want all myrole text to be monospace and bigger.

In my .rst files I can then do:

   Some text that uses :myrole:`my custom role`.

and when Sphinx generates the HTML it will look like:

   link rel=stylesheet href=../_static/customtheme.css type=text/css /
   ...

   pSome text that uses span class=mycustomrolemy custom role/span./p

So, as you can see there is rarely any need to use the :raw-html: role.


 On Thu, Jan 13, 2011 at 10:06 AM, Federico Bruni fedel...@gmail.com wrote:
 2011/1/13 Curiouslearn curiousle...@gmail.com

 Hello All,

 Sphinx seems great. I am trying it out and I think I will start using
 it for most of my writing. I have two basic questions:

 (1) How to get rid of the text v0.1 or something like that which
 refers to the version. I am writing some notes and it is not a
 documentation about any software. I commented out version = 0.1 in
 the conf.py file and then I just got a v.


 In your conf.py you should specify html_title.
 Search this paragraph:

 # The name for this set of Sphinx documents.  If None, it defaults to
 # project vrelease documentation.
 #html_title = None

 --
 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.


 --
 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.



-- 
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] classes inside automodule

On Thu, Jan 13, 2011 at 2:33 PM, Chris Withers ch...@simplistix.co.uk wrote:
 Hi All,

 If I do, for example:


 .. automodule:: testfixtures

  .. class:: Comparison

 ...then I end up with two sections for the Comparison class, one
 auto-generated and one with my manual bits.

 I thought the manual one was supposed to override the automated one?

I don't think so. Did you try the exclude-members option at
http://sphinx.pocoo.org/ext/autodoc.html#directive-automodule ?


 cheers,

 Chris

 PS: This and the other message I just posted on with Sphinx 1.0.6

 --
 Simplistix - Content Management, Batch Processing  Python Consulting
           - http://www.simplistix.co.uk

 --
 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.



-- 
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] Re: |release| substitution inside a download link

2010-11-17 Thread TP

On Wed, Nov 17, 2010 at 3:16 AM, qx guy qx0mons...@googlemail.com wrote:


 On Nov 11, 8:34 am, TP wing...@gmail.com wrote:
   rst_prolog=

   .. |versionG|  replace:: :guilabel:`%s`

    % (version,)
 So now I can do:

   Right-click :guilabel:`blah-`\ |versionG| to do foo.

 Thanks for this tip. But I'm not quite getting this particular
 example. Wouldn't your text expand to

   Right-click :guilabel:`blah-`:guilabel:`10.5`

 (if 10.5 were the value of version)?! That's not quite the same
 as :guilabel:`blah-10.5`, or is it?!

 T.

 --
 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.



Yes. It's not the same thing, but it **looks** right (which is all
that matters in my case).

-- TP

-- 
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: |release| substitution inside a download link

2010-11-10 Thread TP

On Wed, Nov 10, 2010 at 4:08 AM, qx guy qx0mons...@googlemail.com wrote:
 I have the exact same issue using |version|. I want to include it in
 links (which e.g. point from the documentation to online demos which
 follow the same version scheme).

 I think there is a general issue with inline markup, where the
 contents of the markup is not interpreted, and as a consequence macros
 are not expanded. This affects probably more than just links. I
 wouldn't mind going to some effort to overcome this, e.g. by using
 reST directives, I just can't think of how :-/.

 If anybody has an idea how to splice macros into other reST markup,
 I would highly appreciate hearing about this.

 Thomas

 --
 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.



Not sure if this is what you mean but since conf.py is just a Python
file, you can do string substitutions in it.

For example, for I happen to do:

  rst_prolog=

  .. |versionG|  replace:: :guilabel:`%s`

   % (version,)

because I sometimes need to include the version number in :guilabel:
styled text and :guilabel:`blah-|version|` won't work.

So now I can do:

  Right-click :guilabel:`blah-`\ |versionG| to do foo.

As far as links go, you might try this technique in combination with
the sphinx.ext.extlinks – Markup to shorten external links extension.
See http://sphinx.pocoo.org/ext/extlinks.html for details. (Pretty
sure this works for any links not just external ones).

-- 
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.ext.autodoc

On Thu, Oct 21, 2010 at 8:39 AM, Jacob Kaplan-Moss ja...@jacobian.org wrote:
 On Thu, Oct 21, 2010 at 10:09 AM, Maarch monbast...@yahoo.fr wrote:
 I'm trying to use Sphinx to provide a documentation site for my
 company. We  develop an open source software and our source code it's
 not accessible because not well documented.
 It's mentioned that we can generate autodoc from Sphinx but I can't
 find what should I configure to add this extension.
 Can I have help please?

 I can't tell from your query, so I have to ask: have you read the
 documentation? Sphinx, being a tool for documentation, tends to have
 great documentation, and the docs for autodoc don't disappoint:
 http://sphinx.pocoo.org/ext/autodoc.html

 Basically you just make sure the code you want to extract docstrings
 from is on PYTHONPATH, and then do something like::

    .. autoclass:: mymodule.MyClass

 In your docs.

 Jacob

 --
 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.



Maybe the problem is you also have to follow the instructions at:
http://sphinx.pocoo.org/config.html#confval-extensions which are a bit vague.
In this particular case in your conf.py file do:

  sys.path.insert(0, os.path.abspath(PATH_TO_THE_MODULES_YOU_ARE_AUTODOCING))
  extensions = ['sphinx.ext.autodoc']

-- 
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 is the Sphinx home page created?

I've wondered for a while how the Sphinx home page at
http://sphinx.pocoo.org/index.html is created. Unlike all the other
pages on the site there isn't a Show Source link. It also doesn't seem
to be in http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/.

I like the idea of having the Home page be a general overview of the
entire website with no Next navigation in the Navigation bar and a
completely different sidebar from the rest of the site. It still of
course links seamlessly with the normal Sphinx generated
documention. However, it's not completely obvious to me how this was
done.

-- 
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 is the Sphinx home page created?

On 10/21/10, SHIBUKAWA Yoshiki yosh...@shibu.jp wrote:
 Hi,

 I've wondered for a while how the Sphinx home page at
 http://sphinx.pocoo.org/index.html is created. Unlike all the other
 pages on the site there isn't a Show Source link. It also doesn't seem
 to be in http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/.

 This page is not created from reST file.
 See _template directory and you can see the file.

 http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/

 Sphinx supports static html and Jinja2 template
 (you add suffix _t like style.css_t) too.

 I was asked same question from my friend :-)

 --
 #! /usr/bin/python2
 def shibu(shibukawa, yoshiki):
 web = http://www.shibu.jp;
 mail = yosh...@shibu.jp
 twitter = @shibukawa
 return smile!

 --
 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.



Aha, thanks! You also need to add the following to your conf.py file:

master_doc = 'contents'

html_index = 'index.html'

# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'index' :
   ['indexsidebar.html',
'searchbox.html'],
(Other custom sidebars here)
}

# Additional templates that should be rendered to pages, maps page names to
# template names.
html_additional_pages = {'index': 'index.html'}

(and then change the name of your default main .rst page from
index.rst to contents.rst)

The html_index conf.py option doesn't seem to be documented at
http://sphinx.pocoo.org/config.html#options-for-html-output and
perhaps it should be?

Also copy (and then edit)
http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/_templates/index.html
 indexsidebar.html to either the _templates directory or to your
custom theme directory.

Doing make html will now automatically create your new index.html Home page.

-- 
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 is the Sphinx home page created?

On 10/21/10, TP wing...@gmail.com wrote:
 On 10/21/10, SHIBUKAWA Yoshiki yosh...@shibu.jp wrote:
 Hi,

 I've wondered for a while how the Sphinx home page at
 http://sphinx.pocoo.org/index.html is created. Unlike all the other
 pages on the site there isn't a Show Source link. It also doesn't seem
 to be in http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/.

 This page is not created from reST file.
 See _template directory and you can see the file.

 http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/

 Sphinx supports static html and Jinja2 template
 (you add suffix _t like style.css_t) too.

 I was asked same question from my friend :-)

 --
 #! /usr/bin/python2
 def shibu(shibukawa, yoshiki):
 web = http://www.shibu.jp;
 mail = yosh...@shibu.jp
 twitter = @shibukawa
 return smile!

 --
 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.



 Aha, thanks! You also need to add the following to your conf.py file:

 master_doc = 'contents'

 html_index = 'index.html'

 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
 'index' :
['indexsidebar.html',
 'searchbox.html'],
 (Other custom sidebars here)
 }

 # Additional templates that should be rendered to pages, maps page names
 to
 # template names.
 html_additional_pages = {'index': 'index.html'}

 (and then change the name of your default main .rst page from
 index.rst to contents.rst)

 The html_index conf.py option doesn't seem to be documented at
 http://sphinx.pocoo.org/config.html#options-for-html-output and
 perhaps it should be?

 Also copy (and then edit)
 http://bitbucket.org/birkenfeld/sphinx/src/tip/doc/_templates/index.html
  indexsidebar.html to either the _templates directory or to your
 custom theme directory.

 Doing make html will now automatically create your new index.html Home
 page.


It turns out you don't need to add html_index to conf.py. It must be
something that Sphinx needs specifically for itself?

-- 
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] accessing global variables like 'toc'

2010-09-28 Thread TP

On Mon, Sep 27, 2010 at 4:14 AM, Alastair Dent alastair.d...@imgtec.com wrote:
 In some html files I'd like to place a local toc. The variable 'toc' would
 seem to do the trick, but how do I insert it?
 Should I define a block in the layout.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.


I just do:

.. contents::
   :local:

for more info see
http://sphinx.pocoo.org/rest.html?highlight=contents#directives and
http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

-- 
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: MathJax

2010-08-25 Thread TP

On Tue, Aug 24, 2010 at 4:04 PM, Fernando Perez fperez@gmail.com wrote:
On Tue, Aug 24, 2010 at 2:58 PM, Kevin Dunn kgd...@gmail.com wrote:

You can compare how the same HTML page is shown with MathJax or with
Sphinx's built-in pngmath extension:
* mathjax: http://connectmv.com/mathjax-extension/with-mathjax.html
* pngmath: http://connectmv.com/mathjax-extension/with-pngmath.html

MathJax shows better, and the HTML can also be zoomed, and the math
will zoom clearly, unlike PNG.

Wow, beautiful. Many thanks for posting this, I'm sure I'll be making
good use of it soon.

Regards,

--
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.

I've just tried mathjax on Windows XP with Sphinx 1.0.3 and ran into a
two problems. First of all, when testing html files on my local
computer, I couldn't figure out how to get

mathjax_path = '/MathJax/MathJax.js'

in my conf.py to work. At least I couldn't figure out where Firefox
3.6.8 thought /Mathjax was (it apparently wasn't C:\Mathjax). So I
changed to:

mathjax_path = 'file:///C:/MathJax/MathJax.js'

but ran into problems with Sphinx 1.0.3 that are reported and fixed
at
http://bitbucket.org/birkenfeld/sphinx/issue/513/add_javascript-relative_uri-dont-support-local-file-url-syntax-in-sphinx
(the solution is a hack but it works).

I also had to install the mathjax fonts in
\MathJax\fonts\HTML-CSS\TeX\otf\ by following the instructions given
at http://www.mathjax.org/resources/faqs/#image-fonts to get Firefox
to work with my local test files. Otherwise I got a message that my
browser didn't support web-based fonts.

Now all I have to do is figure out how to use TeX :P

Re: [sphinx-dev] Re: MathJax

2010-08-25 Thread TP

On Wed, Aug 25, 2010 at 12:12 AM, TP wing...@gmail.com wrote:
On Tue, Aug 24, 2010 at 4:04 PM, Fernando Perez fperez@gmail.com wrote:
On Tue, Aug 24, 2010 at 2:58 PM, Kevin Dunn kgd...@gmail.com wrote:

MathJax shows better, and the HTML can also be zoomed, and the math
will zoom clearly, unlike PNG.

Wow, beautiful. Many thanks for posting this, I'm sure I'll be making
good use of it soon.

Regards,

I've just tried mathjax on Windows XP with Sphinx 1.0.3 and ran into a
two problems. First of all, when testing html files on my local
computer, I couldn't figure out how to get

mathjax_path = '/MathJax/MathJax.js'

in my conf.py to work. At least I couldn't figure out where Firefox
3.6.8 thought /Mathjax was (it apparently wasn't C:\Mathjax). So I
changed to:

mathjax_path = 'file:///C:/MathJax/MathJax.js'

Now all I have to do is figure out how to use TeX :P

More notes on using MathJax with Sphinx 1.0.3 on Windows:

I decided it was better for local testing and sharing of the
preliminary builds to copy the MathJax folder to my Sphinx projects
_static directory rather than using it from C:\MathJax. Because it
takes up over 120MB(!) of disk space on Windows (only 16MB of that is
the total files size but all those tiny png files take lots of room),
I removed the docs, test, unpacked directories, and most importantly,
disabled image fonts by following the advice of
http://www.mathjax.org/resources/faqs/#fonts-too-big and deleting the
fonts\HTML-CSS\TeX\png directory.

My conf.py file has the following mathjax_path for local testing:

mathjax_path = 'MathJax/MathJax.js'

which correctly points to _static/MathJax/MathJax.js in the generated HTML.

It now takes a annoyingly long time to copy the entire _static
directory (still about 4MB in 440 files) every time I do a make. I
couldn't find any way to tell Sphinx not to bother copying the _static
directory? Once I've done a full make it doesn't change so copying the
entire thing over over is unnecessary.

Additionally, as http://www.mathjax.org/resources/faqs/#ie8-slow says,
you need to add the following to the beginning of the head tag in
order for Internet Explorer 8 not to be ridiculously slow when
displaying pages with MathJax (even only small amounts):

meta http-equiv=X-UA-Compatible content=IE=EmulateIE7

I spent awhile looking in the source code for how to add meta tags
using Sphinx (hint: you can't use the extrahead template block because
that comes too late in the head tag).

As it turns out, all you need to do is use the following docutils meta
directive (http://docutils.sourceforge.net/docs/ref/rst/directives.html#meta)
at the top of each .rst file that contains MathJax code.

.. meta::
:http-equiv=X-UA-Compatible: IE=EmulateIE7

If you have lots of pages with MathJax, you could alternatively put
the above in the new rst_prolog setting
(http://sphinx.pocoo.org/config.html#confval-rst_prolog) in your
conf.py file.

[sphinx-dev] How do you prevent SmartyPants from changing single-quote character?

2010-08-24 Thread TP

My recent suggestion to add back the smartypants.py processEscapes()
function 
(http://bitbucket.org/birkenfeld/sphinx/issue/498/add-escape-sequences-to-smartypants-quote)
was just rejected with the comment:

   I'm against an additional escaping mechanism

additional? How does one currently go about preventing smartypants
from changing quote characters?

-- 
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: MathJax

2010-08-18 Thread TP

On Tue, Aug 17, 2010 at 2:25 PM, David dwarnol...@suddenlink.net wrote:
 Kevin,

 I think developers might be following our posts. I updated (svn)
 MathJax and easy_install -U Sphinx, started anew, and the green font
 is now gone, both in Safari and Firefox.

 Your quote:

 You are correct that the minimal settings will work, however, I left
 the span and div elements in there: others might have existing CSS
 styling settings, so these wrapping elements should allow their CSS to
 be easily customized.  Would it be useful to have a mathjax.py setting
 to make this output optional?

 I don't think I know enough to answer this question. From what I have
 read (quite a bit), MathJax has ways of configuring the mathematics,
 so I don't really see a need for the class=math guys.

 But, I am very new to this.

 David.

 --
 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.



I say keep it. It doesn't hurt and is helpful if people want to style
math generated stuff differently from other things. One of the
things that Sphinx 1.0 changed was adding the type of the node to
the HTML class attribute just so elements could be separately
styled. For example:

   strong class=commandrm/strong is strong/p

Given that, it's easy to change the rendering of command roles to be
italic, underlined, etc. It doesn't have to be strong (bold)
anymore.

-- 
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] Laying out documentation for a large project

2010-04-27 Thread TP

On Fri, Apr 16, 2010 at 8:57 AM, gslindstrom gslindst...@gmail.com wrote:
 Hello,

 We are starting a large project where I work and I would like to start
 documenting it *now* rather than later.  Sphinx looks like the ideal
 tool for the job (I've been playing with it for a month or two but,
 now, it's time to get serious).

 Are there thoughts on whether I should put all my documentation in one
 directory (docs) under the main project directory or would I have the
 same docs directory but with each sub-part of the project (build,
 www, lib, test) having it's own docs directory holding information
 on that particular area and having the master docs tie them all
 together?  My thinking is it might be nice to have the documentation
 closer to the actual code.

 If I were to have separate doc directories (one under each sub-part),
 how do I link the main toctree (in myproject/docs/source/index.rst) to
 the sub-parts (say, my_project/www/docs/index.rst)?  I've tried Web
 Documentation ../../www/docs/index, but it does not find it.  I've
 heard that I can't go up like that to get to other directories;
 don't recall where I read it, but I thought I would ask here.

 And, as long as I am asking, if I have another routine that I have
 already documented with Sphinx, how do I include it with this project
 (it's a routine extending the logger routine in the Standard Library
 that my_project will use.  I don't want it in the user
 documentation, but would like it in the technical referrence portion
 of my_project documentation.  Perhaps it is enough to have a
 dependencies page listing all of the third-party routines.

 I hope I have made sense, because I'm a bit overwhelmed.  I've never
 been a fan of documentation but am committed to giving this a go.

 Thanks for your replies,

 Greg Lindstrom
 Novasys Health (Little Rock, AR)

You might want to look at the doc directory of a recent Python (2.6.x
or 3.1.x) *source* distribution from http://python.org/download/. It's
probably the biggest real world example of using Sphinx.

-- 
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] sidebars disappeared

2010-04-19 Thread TP

On Mon, Apr 19, 2010 at 4:10 AM, mark mark.fi...@googlemail.com wrote:
 Hi Georg,

 I pulled 0.66 from the repository this morning. Now the sidebars
 disappeared. I tried to fix it with additional configurations but so
 far I had no luck. I created a new documentation with quickstart and
 this has no sidebars, too.

 here is the modified conf.py for the new configuration
 ...
 html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}

 html_theme = 'sphinxdoc'
 #html_theme = 'default'
 html_theme_options = {
   nosidebar: false
 }
 ...
 Hopefully you have an idea on how I get my sidebar back without going
 back to ~0.62.

 Cheers,
 Mark

Don't know if this has propagated to 0.66 but the development version
of sphinx has new format for html_sidebars. See
http://sphinx.pocoo.org/latest/config.html#options-for-html-output for
details. In particular, you use '**' as the key to specify *all*
documents.

In you case try saying:

html_sidebars = {'**': ['indexsidebar.html', 'searchbox.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] SVG figures in Firefox

2010-04-13 Thread TP

2010/4/13 Václav Šmilauer oty...@gmail.com:
 Hi there,

 I am not sure whether this is Firefox-specific... I am not able to see
 SVG figures in HTML output, with Firefox 3.6.3. It doesn't display
 anything at all, just blank space. Those SVG were created byt
 inkscape. Is it possible that Firefox is _that_ picky about svg files?

 Does that work for everybody else normally? In that case I would start
 investigating inkscape/firefox svg compatibility.

 Cheers, v.


Make a tiny HTML test file that only contains your SVG image?

Also see: http://www.mozilla.org/projects/svg/status.html and
http://www.mozilla.org/projects/svg/#status:

Big areas of the SVG specification where we're still lacking include
filters, svg defined fonts, and declarative animations.

-- 
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 turn off alphabetical ordering ?

2010-04-12 Thread TP

On Mon, Apr 12, 2010 at 8:33 AM, Michael Rule mrule7...@gmail.com wrote:
 I would like to preserve source ordering in my documentation. I tried adding
 autodoc_member_order = 'groupwise'
 to the conf.py file, but this doesn't seem to do anything. What is the
 proper way to turn off alphabetical sorting ??

 --mrule

In the thread [sphinx-dev] Ordering members by order in source code?

Georg Brandl said see
http://bitbucket.org/birkenfeld/sphinx-domains/changeset/3474d539292a/.
#187: Added support for source ordering of members in autodoc, with
``autodoc_member_order = 'bysource'``.

This is apparently only in the development (1.0) version.

-- 
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 turn off alphabetical ordering ?

2010-04-12 Thread TP

On Mon, Apr 12, 2010 at 11:17 AM, Michael Rule mrule7...@gmail.com wrote:
 hmm, naively tried installing 1.0 with the following commands
 hg clone http://bitbucket.org/birkenfeld/sphinx
 sudo python setup.py develop

 With
 autodoc_member_order = 'bysource'
 at the bottom of the config file.

 Nothing changed so I tried re-directing the SPHINXBUILD variable in
 the makefile to the new sphinx-build script
 SPHINXBUILD   = /home/mrule/installers/sphinx/sphinx-build.py

 Members still seem to be sorted in alphabetical order. Granted, I am
 listing the classes in a module, so maybe 'bysource' doesn't apply
 here ? Alternatively I am still somehow using the old sphinx builder
 and need to figure out how to point everything to the new version ?

 --mrule

 On Mon, Apr 12, 2010 at 12:21 PM, Michael Rule mrule7...@gmail.com wrote:
 thanks, so putting
 autodoc_member_order = 'bysource'

 at the bottom of conf.py would work, if I had this version ?
 and I assume there is some way to update to this version ?

 On Mon, Apr 12, 2010 at 12:15 PM, TP wing...@gmail.com wrote:
 On Mon, Apr 12, 2010 at 8:33 AM, Michael Rule mrule7...@gmail.com wrote:
 I would like to preserve source ordering in my documentation. I tried 
 adding
 autodoc_member_order = 'groupwise'
 to the conf.py file, but this doesn't seem to do anything. What is the
 proper way to turn off alphabetical sorting ??

 --mrule

 In the thread [sphinx-dev] Ordering members by order in source code?

 Georg Brandl said see
 http://bitbucket.org/birkenfeld/sphinx-domains/changeset/3474d539292a/.
 #187: Added support for source ordering of members in autodoc, with
 ``autodoc_member_order = 'bysource'``.

 This is apparently only in the development (1.0) version.

 --
 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.




 --
 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.



Looks like you **HAVE** to currently use
http://bitbucket.org/birkenfeld/sphinx-domains/. The bysource changes
haven't yet been merged back into the main sphinx repository. Sorry.

-- 
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] Multiple stylings of preformatted text

2010-04-09 Thread TP

On Thu, Apr 8, 2010 at 11:34 PM, malthe mbo...@gmail.com wrote:
 In my document I have two types of text blocks corresponding to user's
 text input and output. How do I tell Sphinx to assign a particular
 HTML-class to each of them (e.g. input, output) such that I may
 assign different colors in a CSS stylesheet?

 Any hints appreciated!

 \malthe

 --
 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.



Take a look at the docutils class directive:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#class.

-- 
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] customsidebar

2010-04-08 Thread TP

On Thu, Apr 8, 2010 at 7:30 AM, Jan Ulrich Hasecke
juhase...@googlemail.com wrote:
 I found

 
 {%- if customsidebar %}
 {% include customsidebar %}
 {%- endif %}

 in layout.html

 How can I use it. I did not find customsidebar in the documentation.

 juh

See http://sphinx.pocoo.org/config.html#confval-html_sidebars.

The latest tip version has better documentation and support for custom sidebars:
http://sphinx.pocoo.org/latest/config.html#confval-html_sidebars

-- 
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] ReStructuredTextToolsForGedit

2010-04-03 Thread TP

On Mon, Mar 29, 2010 at 11:48 PM, werner wbru...@free.fr wrote:
 I use UliPad, but it has the same limitations - it would be nice if there is
 a way to preview a single .rst file - with Sphinx directives also working,
 but I don't think there is such a build command in Sphinx at this time -
 would be very happy if someone would correct me on this.

Under windows xp the following works to build a single file (and files
with dependent toctrees):

  sphinx-build.exe -b html -d _build\doctrees . _build subdir/test.rst
  Running Sphinx v1.0
  loading pickled environment... done
  building [html]: 1 source files given on command line
  updating environment: 0 added, 1 changed, 0 removed
  reading sources... [100%] subdir/test

  looking for now-outdated files... none found
  pickling environment... done
  checking consistency... done
  preparing documents... done
  writing output... [ 33%] index
  writing output... [ 66%] subdir/index
  writing output... [100%] subdir/test

  writing additional files... search
  copying static files... done
  dumping search index... done
  dumping object inventory... done
  build succeeded.

I presume something similar would work on other platforms.

-- 
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] Linking from Doc logo or rel bar to website

2010-04-01 Thread TP

On Thu, Apr 1, 2010 at 8:21 AM, Paulette pziegf...@gmail.com wrote:
 Hi,

 Is there any way to link from logo in the side bar  of the
 documenation OR from the relation bar to web address? (Currently from
 any place in the docs, clicking on the logo or rel bar text takes you
 to the main TOC.)

 We are developing our project website (openmdao.org) and use Trac to
 host our documentation and for bug tracking. On the main page, if
 users click on the Support tab and then select Docs, they go to
 our Sphinx-generated documentation. (The docs open in the same
 window.)  But the only way to get back to openmdao.org is via the
 back arrow. If users have been moving among the documents, it is not
 so convenient.

 So, we would like to link from the logo or rel bar (anywhere in the
 docs) back to the Trac main page. Can this be done?

 Thanks,
 Paulette

 --
 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.



I believe you can just do the following to layout.html in your custom
theme directory (see
http://sphinx.pocoo.org/templating.html#working-with-the-builtin-templates
for details):

{% extends basic/layout.html %}

{% block rootrellink %}
  lia href=http://openmdao.org;OpenMDAO Home/a{{ reldelim1 }}/li
  {{ super() }}
{% endblock %}

{% block sidebarlogo %}
img href=http://openmdao.org; src={{
pathto(_static/OpenMDAOLogo_200x56.png, 1) }} border=0
alt=OpenMDAO Home/
{% endblock %}

-- 
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] Linking from Doc logo or rel bar to website

2010-04-01 Thread TP

On Thu, Apr 1, 2010 at 3:28 PM, TP wing...@gmail.com wrote:
 On Thu, Apr 1, 2010 at 8:21 AM, Paulette pziegf...@gmail.com wrote:
 Hi,

 Is there any way to link from logo in the side bar  of the
 documenation OR from the relation bar to web address? (Currently from
 any place in the docs, clicking on the logo or rel bar text takes you
 to the main TOC.)

 We are developing our project website (openmdao.org) and use Trac to
 host our documentation and for bug tracking. On the main page, if
 users click on the Support tab and then select Docs, they go to
 our Sphinx-generated documentation. (The docs open in the same
 window.)  But the only way to get back to openmdao.org is via the
 back arrow. If users have been moving among the documents, it is not
 so convenient.

 So, we would like to link from the logo or rel bar (anywhere in the
 docs) back to the Trac main page. Can this be done?

 Thanks,
 Paulette

 --
 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.



 I believe you can just do the following to layout.html in your custom
 theme directory (see
 http://sphinx.pocoo.org/templating.html#working-with-the-builtin-templates
 for details):

 {% extends basic/layout.html %}

 {% block rootrellink %}
  lia href=http://openmdao.org;OpenMDAO Home/a{{ reldelim1 }}/li
  {{ super() }}
 {% endblock %}

 {% block sidebarlogo %}
 img href=http://openmdao.org; src={{
 pathto(_static/OpenMDAOLogo_200x56.png, 1) }} border=0
 alt=OpenMDAO Home/
 {% endblock %}


Oops. Should have been:

{% block sidebarlogo %}
a href=http://openmdao.org;
 img src={{ pathto(_static/OpenMDAOLogo_200x56.png, 1) }}
border=0 alt=OpenMDAO Home/
/a
{% endblock %}

-- 
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] ePub builder

2010-03-31 Thread TP

ePub generation is in the development version. See
http://sphinx.pocoo.org/latest/builders.html#sphinx.builders.epub.EpubBuilder.

On Wed, Mar 31, 2010 at 2:38 PM, Roberto Alsina
rals...@netmanagers.com.ar wrote:
 A while ago, there was some mention of work on an ePub builder. Was there any
 progress? Anyone is interested in it?

 I may want to take a stab at it (not yet, though).

 --
 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.



-- 
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] Included non-rst files not copied to _source directory

2010-03-30 Thread TP

I implemented rst_prologue option in conf.py here:
http://bitbucket.org/tpowers/sphinx/changeset/c5ad17aa65cb/ (it's only
a few changed lines).

On Mon, Mar 29, 2010 at 7:29 PM, Fernando Perez fperez@gmail.com wrote:
 On Mon, Mar 29, 2010 at 2:42 PM, TP wing...@gmail.com wrote:


 However, as described in my Include directive doesn't correctly support
 'absolute' paths message, includes seem to be useless when used from
 multiple subdirs in the same project.

 Unless I'm missing something, there doesn't seem to be any easy way to
 use the same include directive from multiple subdirs. You might be able
 to use different 'relative' paths depending on where you are including
 from but that seems more bother than it's worth.

 Instead, for now, I'll just implement a rst-prologue conf.py option
 (analogous to the rst-epilog option) and avoid includes altogether.

 My (hackish, ugly but functional) solution to this is to use

 include: foo.txt

 and in *every* directory (but the project topmost one, of course),
 have a symlink

 foo.txt - ../foo.txt

 so they eventually all resolve at the top.  Not pretty, but works for me :)

 Cheers,

 f

 --
 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.



-- 
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] Included non-rst files not copied to _source directory

http://sphinx.pocoo.org/rest.html#substitutions says:

If you want to use some substitutions for all documents, put them into
a separate file and include it into all documents you want to use them
in, using the include directive. Be sure to give the include file a file
name extension differing from that of other source files, to avoid
Sphinx finding it as a standalone document.

However, if you DO name your included file with an extension other than
.rst (say .hr), it will NOT be copied over to the _build/html/_sources
directory.

Additionally, in the latest trunk revision, the unused_docs conf.py
option no longer works, so if you change the name back to include .rst,
you then get the WARNING: document isn't included in any toctree
message.

If instead you add the file to the new exclude_patterns option, then
again it no longer gets copied to the _sources directory.

-- 
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] Include directive doesn't correctly support absolute paths

.. include:: /include.rst

in the file c:\docs\project\subdir\index.rst

looks for c:\include.rst instead of looking in the top source directory
c:\docs\project\include.rst.

Conversely, the image directive docs
(http://sphinx.pocoo.org/rest.html#images) say:

   .. image:: gnu.png

   When used within Sphinx, the file name given (here gnu.png) must
   either be relative to the source file, or absolute which means that
   they are relative to the top source directory. For example, the file
   sketch/spam.rst could refer to the image images/spam.png as
   ../images/spam.png or /images/spam.png.

So how can I include files that are in the top source directory, no
matter how far down in the project hierarchy the current source file is?

(Given how simple it looks to be, perhaps I'll just implement
rst-prologue and avoid the whole include issue)

-- 
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] Included non-rst files not copied to _source directory

Yea, I was just ignoring the warning message.

However, as described in my Include directive doesn't correctly support
'absolute' paths message, includes seem to be useless when used from
multiple subdirs in the same project.

Unless I'm missing something, there doesn't seem to be any easy way to
use the same include directive from multiple subdirs. You might be able
to use different 'relative' paths depending on where you are including
from but that seems more bother than it's worth.

Instead, for now, I'll just implement a rst-prologue conf.py option
(analogous to the rst-epilog option) and avoid includes altogether.

On Mon, Mar 29, 2010 at 12:30 PM, Max Battcher m...@worldmaker.net wrote:
 TP wrote:

 Additionally, in the latest trunk revision, the unused_docs conf.py
 option no longer works, so if you change the name back to include .rst,
 you then get the WARNING: document isn't included in any toctree
 message.

 That warning is certainly harmless, if that's your biggest concern against
 using .rst as the file extension. In an earlier thread Georg mentioned that
 maybe it was time that warning was rewritten or rethought, because it looks
 scarier than it is intended to be. From what it appears to me, it's meant to
 be something of a Hey, did you know you didn't add this file to your
 toctree? reminder than a Whoops, things are broken because you have a
 document that you haven't put into a toctree. I think that maybe the
 documentation you cited should be rewritten as well.

 --
 --Max Battcher--
 http://worldmaker.net

 --
 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.



-- 
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: ReStructuredTextToolsForGedit