[sphinx-dev] Feature Request: Auto-Extracting Examples

2012-01-06 Thread Bruce Eckel
I'd love to see some kind of tag that indicates that something is, or is
part of, a working example, so that Sphinx would automatically extract the
example and it could be downloaded, run, etc.

I ask for this because I see too much documentation where the author says
"here's how to do it" and then gives some untested code fragment. I think
if this (admittedly low, but apparently enough to keep people from doing
it) hurdle were removed, we'd see far more working examples.

I always have the first line of a code listing example as a comment that
gives the name of the file in the comment, but if you had a tag that
required the file name then you could use that to extract the code AND to
create a caption for the example giving the file name.

If this doesn't make sense, I can answer questions. I've been doing this
kind of thing in my books for over 15 years.

-- Bruce Eckel
www.Reinventing-Business.com
www.MindviewInc.com

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

2008-11-09 Thread Bruce Eckel
Not the way I've seen it used, for example, in the python docs it's used to
tell people other resources to look at.

On Sun, Nov 9, 2008 at 3:31 AM, Georg Brandl <[EMAIL PROTECTED]> wrote:

>
> I don't think this fits with the intention of the seealso directive.
> It is meant as an admonition, like .. note:: or .. warning::
>
> Georg
>
> Bruce Eckel schrieb:
> > Pretty much just like any other level-2 header (that is, right below
> > chapter level).
> >
> > On Sat, Nov 8, 2008 at 4:32 AM, Georg Brandl <[EMAIL PROTECTED]
> > <mailto:[EMAIL PROTECTED]>> wrote:
> >
> >
> > Bruce Eckel schrieb:
> > > I like this tag, but is there a way to make it show up in the
> various
> > > tables of contents? Thanks...
> >
> > Not that I know of. How would you want it to show up?
> >
> > Georg
> >
> >
> >
> >
> >
> > --
> > Bruce Eckel
> >
> >
> > >
>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: seealso

2008-11-08 Thread Bruce Eckel
Pretty much just like any other level-2 header (that is, right below chapter
level).

On Sat, Nov 8, 2008 at 4:32 AM, Georg Brandl <[EMAIL PROTECTED]> wrote:

>
> Bruce Eckel schrieb:
> > I like this tag, but is there a way to make it show up in the various
> > tables of contents? Thanks...
>
> Not that I know of. How would you want it to show up?
>
> Georg
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



seealso

2008-11-06 Thread Bruce Eckel
I like this tag, but is there a way to make it show up in the various tables
of contents? Thanks...

-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: How to inter-link Sphinx projects?

2008-11-03 Thread Bruce Eckel
Not sure if I know what you're asking, but if you just want to combine them
into a single document, put a line in the toctree of your index.rst. For
example, here's what mine looks like:

Python 3 Patterns & Idioms
==

Contents:

.. toctree::

   _Front/Contributors.rst
   _Front/NoteToReaders.rst
   _Front/Introduction.rst
   _Front/TeachingSupport.rst
   _Front/Rules.rst
   _Front/Part1.rst
   quickPython/quickPython.rst
   unitTesting/unitTesting.rst
   LanguageChanges/LanguageChanges.rst
   PythonDecorators/PythonDecorators.rst
   GeneratorsIterators/GeneratorsIterators.rst
   Comprehensions/Comprehensions.rst
   CoroutinesAndConcurrency/CoroutinesAndConcurrency.rst
   jython/jython.rst
   _Front/Part2.rst
   MachineDiscovery/MachineDiscovery.rst
   CanonicalScript/CanonicalScript.rst
   _Front/Part3.rst
   patternConcept/patternConcept.rst
   singleton/singleton.rst
   appFrameworks/appFrameworks.rst
   fronting/fronting.rst
   stateMachine/stateMachine.rst
   decorator/decorator.rst
   iterators/iterators.rst
   factory/factory.rst
   functionObjects/functionObjects.rst
   changeInterface/changeInterface.rst
   tableDriven/tableDriven.rst
   observer/observer.rst
   multipleDispatching/multipleDispatching.rst
   visitor/visitor.rst
   patternRefactoring/patternRefactoring.rst
   projects/projects.rst

Indices and tables
==

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`


On Mon, Nov 3, 2008 at 8:13 AM, Timmie <[EMAIL PROTECTED]> wrote:

>
> Hello Sphinx-community,
> I have got a question regarding the referencing to other ReSt
> formatted documents.
>
> I have a project progB. This builds up a lot on progA (python
> package). Both have their individual Shinx documentation:
>
> progA/doc/source/index.rst
> progB/doc/source/index.rst
>
> How do I link
>
> progB/doc/source/requirements.rst to progA/doc/source/index.rst
>
> I would like to achive that each time, the documentation for progB is
> build, the documentation for progB gets included.
>
> Thanks in advance for your help and hints,
> Timmie
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: option list question

2008-11-03 Thread Bruce Eckel
I only know about it because I came across it while studying the Sphinx
docs, and it mentioned that Smarty was used to do things like putting in
smart quotes.
Oops. It's in the build configuration file docs, smartypants, not smarty:

html_use_smartypants<http://sphinx.pocoo.org/config.html?highlight=quotes#confval-html_use_smartypants>If
true, *SmartyPants* will be used to convert quotes and dashes to
typographically correct entities. Default: True.


On Mon, Nov 3, 2008 at 9:25 AM, Doug Hellmann <[EMAIL PROTECTED]>wrote:

>
> On Nov 3, 2008, at 11:04 AM, Bruce Eckel wrote:
>
> I'll bet that's smarty, it might be turning it into an en-dash or em-dash.
>
>
> I don't know what smarty is.  Is it something I can turn off?  Is it
> context sensitive in some way, so I could disable it only for option lists?
>
>
>
> On Mon, Nov 3, 2008 at 7:53 AM, Doug Hellmann <[EMAIL PROTECTED]>wrote:
>
>>
>> I have an option list, formatted like:
>>
>> """
>> -h
>>   Displays abbreviated help message.
>>
>> --help
>>   Displays complete usage information.
>> """
>>
>> The output in HTML and PDF from version 0.4.2 shows the "--" in front
>> of "--help" converted to a single hyphen character.
>>
>> Am I leaving out some markup that would prevent that?  If I mark the
>> option for mono-space formatting the conversion doesn't happen, but
>> then the result doesn't use the "option-list" class, so I can't apply
>> some of the CSS styles I want to use.
>>
>> Thanks,
>> Doug
>>
>>
>>
>>
>
>
> --
> Bruce Eckel
>
>
>
>
>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: option list question

2008-11-03 Thread Bruce Eckel
I'll bet that's smarty, it might be turning it into an en-dash or em-dash.

On Mon, Nov 3, 2008 at 7:53 AM, Doug Hellmann <[EMAIL PROTECTED]>wrote:

>
> I have an option list, formatted like:
>
> """
> -h
>   Displays abbreviated help message.
>
> --help
>   Displays complete usage information.
> """
>
> The output in HTML and PDF from version 0.4.2 shows the "--" in front
> of "--help" converted to a single hyphen character.
>
> Am I leaving out some markup that would prevent that?  If I mark the
> option for mono-space formatting the conversion doesn't happen, but
> then the result doesn't use the "option-list" class, so I can't apply
> some of the CSS styles I want to use.
>
> Thanks,
> Doug
>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Version control

2008-11-02 Thread Bruce Eckel
One nice thing about Bazaar is that they've integrated it with Tortoise on
Windows, so you can do things within the GUI rather than being forced to use
the command line.

On Sat, Nov 1, 2008 at 11:25 PM, Gour <[EMAIL PROTECTED]> wrote:

> >>>>> "Yarko" == Yarko T <[EMAIL PROTECTED]> writes:
>
> Yarko> I used to be on the hg end also - but I was participating in
> Yarko> projects on Launchpad; that started to erode my preference I
> Yarko> think later (>1.5?)  releases of bzr are "snappier"...
>
> +1 for bzr & LP (coming from DVCS land of darcs), although not being
> contributor (yet), but in the process of learning Python...
>
>
> Sincerely,
> Gour
>
> --
>
> Gour  | Zagreb, Croatia  | GPG key: C6E7162D
> 
>



-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Version control (was Re: Autosummary)

2008-11-01 Thread Bruce Eckel
I'm using everything Launchpad, including Bazaar, for my project. That said,
I'm still learning DVCS and Bazaar, but I like all the support tools that
Launchpad provides, and that they're all in one place, and that there's
money behind development.

On Sat, Nov 1, 2008 at 12:15 PM, Yarko T <[EMAIL PROTECTED]> wrote:

> DVCS is nice - and lightweight on a potential contributor's local machine..
>
> Could we keep it python-ish, so that contributing platforms don't get in
> the way?
> The nice thing about SVN is is seems to run everywhere
>
> mercurial too (but you need to compile "C" code if not);
> bazaar is all python;
>
> I'd vote for one of the later two (hg or bzr).  In fact, I've found a "most
> of what I need" bazaar site (launchpad), but not found a hosting place
> similarly configured for hg, so would be curious to hear what other people
> are using for hg source hosting, that includes (at least) a wiki and issue
> tracker.
>
> Thanks,
> Yarko
>
>
> On Sat, Nov 1, 2008 at 11:16 AM, Rok Garbas <[EMAIL PROTECTED]> wrote:
>
>>
>> On Sat, Nov 1, 2008 at 4:14 PM, Georg Brandl <[EMAIL PROTECTED]> wrote:
>> > So, I'm asking all of you: what would you prefer -- SVN at Google,
>> > with very liberal commit policies, or Mercurial?
>>
>> i'm not (yet) a contributor, but i'm working extensivly with sphinx
>> last month and will continue in the future. it would be nice to see
>> DVCS. could git be possible option?
>> (http://git.or.cz/gitwiki/GitBenchmarks)
>>
>>
>> (my intention is not to get into "best dvcs war" here, i'm just proposing
>> git)
>>
>> --
>> Rok Garbas
>> http://sharbas.blogspot.com/
>>
>>
>>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Styling text?

2008-11-01 Thread Bruce Eckel
That just seems to create regular body font. Plus it requires an argument,
which also comes out in regular body font.

On Sat, Nov 1, 2008 at 8:40 AM, Georg Brandl <[EMAIL PROTECTED]> wrote:

>
> Bruce Eckel schrieb:
> > Is there some way to create a text style? I want to be able to emphasize
> > one or two introductory sentences at the beginning of each chapter.
> >
> > So far, all I've found is
> >
> > .. raw:: html
> >
> >The vision for the book.
> >
> > But this is apparently the heavy-handed approach (and requires a
> > separate tag for Latex).
> >
> > If there is at least a macro or extension technique that would be better.
>
> Perhaps you can try the "sidebar" directive?
>
> .. sidebar:: Introduction
>
>   Introductory sentences
>
> Georg
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Icon doesn't seem to get used locally

2008-10-30 Thread Bruce Eckel
If you set an icon and compile it in, the icon doesn't seem to show up when
you open the file locally.
For what it's worth, the icon line produced by sphinx is:




-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Styling text?

2008-10-30 Thread Bruce Eckel
Is there some way to create a text style? I want to be able to emphasize one
or two introductory sentences at the beginning of each chapter.
So far, all I've found is

.. raw:: html

   The vision for the book.

But this is apparently the heavy-handed approach (and requires a separate
tag for Latex).

If there is at least a macro or extension technique that would be better.

-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: how do I create a preface?

2008-10-29 Thread Bruce Eckel
On that subject, it seems like the markup
###
Section Title
###

is declared in the sphinx docs as a "section", but the result in the table
of contents looks like just another chapter. Is there a way to have it stand
out as a section?

Thanks.

On Wed, Oct 29, 2008 at 8:05 AM, Doug Hellmann <[EMAIL PROTECTED]>wrote:

>
> I have some generic information I would like to include in a preface
> for a manual I'm converting to PDF (stuff like "Intended Audience",
> etc.).
>
> If I format my index.rst file like:
>
> """
> ###
> Book Title
> ###
>
> ==
> Intended Audience
> ==
>
> Describe people who want to read this manual.
>
> .. toctree::
>chapter1
>etc.
> """
>
> Then all of the parts of the toctree show up as sub-sections of an
> "Intended Audience" chapter.
>
> I don't really want the material in a chapter of its own, but I could
> do that.
>
> Is there some directive or markup I can use to include a preface with
> subsections without having the preface itself made into a chapter?
>
> Thanks,
> Doug
>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: How do I convert a word document to reStructured text?

2008-10-28 Thread Bruce Eckel
Well, I've just converted my Word book to Sphinx, and "partial automation"
is the key. Actually, you can automate a lot of it but it's a cost-benefit
analysis each time. For example, If I had a lot more headers it would have
made sense to write a VBA Macro to put the Rest underlines on the headers,
but I just did it by hand.
What I ended up doing is creating a build system that would take the word
doc and convert it to ASCII, then do some post-processing (breaking it up
into individual files, modifying the contents, etc.) But I kept it in Word
and just continued to run the build until I was sure I had everything out
that I wanted (and I jumped the gun on a few things like stripping out some
of the indexing -- seemed like a good idea at the time but now I wish I
hadn't). And finally I felt like I didn't need the word doc anymore and just
started editing in Sphinx, but before that I did any edits in Word and ran
the converter.

To get you started, here's the part that automatically writes the Word doc
into an ASCII file:

if not os.path.exists("TIPython.txt") or os.path.getmtime("TIPython.doc") >
os.path.getmtime("TIPython.txt"):
import win32com.client
import sys, os
from win32com.client import constants # Run makepy (part of Pythonwin)
if this doesn't work
o = win32com.client.Dispatch("Word.Application")
o.Visible = 0
here = os.getcwd()
o.Documents.Open(os.path.join(here, "TIPython.doc"))
o.ActiveDocument.AcceptAllRevisions()
o.ActiveDocument.SaveAs(FileName = os.path.join(here, "TIPython.txt"),
FileFormat = constants.wdFormatText)
o.ActiveDocument.Close()
print "(TIPython.doc saved as TIPython.txt)"

On Tue, Oct 28, 2008 at 10:35 AM, Martin Hans <[EMAIL PROTECTED]> wrote:

>  Hi,
> Currently our product's user manual is written in Word, but we'd like to
> move all our documentation into Sphinx. Does anybody have an idea how I can
> do this at least partially automatically?
>
> Thanks.
>
> Martin
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: better css for the sidebar?

2008-10-27 Thread Bruce Eckel
It would be great to have an example of customization to start from; I would
also like to do a little customization although I'm OK with the layout for
now.
One thing I'd love to do is to put an image of the book cover on the bottom
of the left sidebar.

On Mon, Oct 27, 2008 at 1:58 PM, _Mark_ <[EMAIL PROTECTED]> wrote:

>
> (Background: inspired by use of sphinx for docs.python, I'm converting
> a bunch of old-ugly dev-blog-ish pages (thok.org) to rst so I can feed
> them to sphinx - architecturally it actually fits the site model quite
> well, and gets me a bunch of stylistic bits for-cheap...)
>
> Has anyone come up with a cleaner version of the sidebar?  I noticed
> it handling font size changes and small screens (EEEpc for example)
> poorly (the biggest issue is the search box overlapping the text,
> which I noticed in pypubsub too) and dug in enough to discover the
> sidebar and main text are absolutely positioned with pixel sizes...
> and while this is not wrong (is there even a concept of "wrong" in
> CSS? :-) I'd hope something more structural would work better, but
> that might not be true, and I'm wondering if someone's already looked
> at the problem...
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Simple change to headers and footers

2008-10-27 Thread Bruce Eckel
The link on my headers and footers says:

Python 3 Patterns & Idioms v1.0 documentation »

How do I change or remove the "v1.0 documentation" part?

Thanks.

--
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Column/row spanning for latex

2008-10-22 Thread Bruce Eckel
I am also interested in better ways to produce PDF from Sphinx.
The "Python 3 Patterns & Idioms" book will be written in Sphinx, and if it
could go to camera-ready copy directly, rather than having to convert it to
something else first, that could greatly improve the book process,
especially for translations to other languages (I'm envisioning Python user
groups in other countries doing translations and creating print-on-demand
books to raise money for their user groups, or something like that).

On Wed, Oct 22, 2008 at 11:48 AM, Georg Brandl <[EMAIL PROTECTED]> wrote:

>
> Roberto Alsina schrieb:
> > On Wednesday 22 October 2008 02:36:49 Roger Binns wrote:
> >> I'm in the process of shifting to sphinx from plain html doc and
> >> particularly liked that I could get PDF out of this.  (Note that I
> >> couldn't care less about latex.  The conversion could happen via magic
> >> pixie dust for all I care :) )
> >>
> >> Exception occurred:
> >>   File "/usr/lib/python2.5/site-packages/Sphinx-0.4.3-py2.5.egg/sphinx/
> >> latexwriter.py", line 512, in visit_entry
> >> raise NotImplementedError('Column or row spanning cells are '
> >>
> >> I have some simple column spanning in a table.  Will Sphinx Latex
> >> writer be gettting this ability in the near future or are there any
> >> alternate ways of getting PDF?
>
> I can't promise it, but I'll put implementing this on the todo list.
>
> > Rst2pdf (http://rst2pdf.googlecode.com) supports that but there isn't
> yet a
> > way to use it from sphinx easily. I asked here if anyone was interested
> and
> > there were some responses, but nothing came of it :-(
>
> I'm still interested, but I don't have the time to write the glue code
> myself.
>
> Georg
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Python programs are not always getting pygmentized

2008-10-19 Thread Bruce Eckel
Unlikely. The first example that doesn't pygmentized should work with any
Python:

# quickPython/strings.py
print "That isn't a horse"
print 'You are not a "Viking"'
print """You're just pounding two
coconut halves together."""
Print '''"Oh no!" He exclaimed.
"It's the blemange!"'''
print r'c:\python\lib\utils'


On Sun, Oct 19, 2008 at 2:08 PM, Christophe de VIENNE
<[EMAIL PROTECTED]>wrote:

>
> I think I have observed such a behavior when the python code sample
> is, for example valid python 2.6 but not python 2.4, which is the
> version of python I use to compile the docs.
>
> It seemed that sphinx try to compile the sample to decide it it is
> valid python, and if not the code doesn't get coloured.
>
> I'm not 100% sure of this but if it can help...
>
> Christophe de Vienne
>
> 2008/10/19 Bruce Eckel <[EMAIL PROTECTED]>:
> > Not really clear why it works most of the time, and not some of the time.
> > In particular, you see examples of this in the first and second chapters.
> > I've attached the source files; all you need to do is "make html"
> >
> > --
> > Bruce Eckel
> >
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: How to create Pygments extension for Sphinx

2008-10-17 Thread Bruce Eckel
Yes, do send it in. In the Jython chapter I've got Java code and it would be
nice to pygment-ize that.

On Fri, Oct 17, 2008 at 1:00 PM, Gabriel Gellner <[EMAIL PROTECTED]>wrote:

>
> On Fri, Oct 17, 2008 at 10:27:44AM -0700, Glenn Hutchings wrote:
> >
> > Hi there.  I posted this to comp.lang.python recently; no answers so
> > far.  Then I spotted this group...
> >
> > I'm writing Sphinx documentation for a non-Python program. The program
> > has an input file syntax suitable for highlighting using Pygments but,
> > obviously, Pygments knows nothing about it.  I've created a Pygments
> > lexer which should highlight things, but how do I tell Pygments about
> > the new lexer, short of manually adding the Python source to the
> > Pygments "lexers" directory (clearly the Wrong Thing)?
> >
> > I've scoured Sphinx, Pygments and setuptools documentation, and
> > seemingly the only way is to register a setuptools 'entry point' in
> > the setup() function -- but that seems to imply I'm installing a
> > Python package, which I'm not.  Do I have to create one, or is there
> > another way?
> >
> You can register an extension in the Sphinx conf.py file, say you have a
> pygments extension called foo_highlighting (which is an importable module
> or
> package . . .). Then add the lines:
>
># If your extensions are in another directory, add it here.
>sys.path.append('sphinxext')
>
># Import support for  foo syntax highlighting (lives
># in the sphinxext directory defined above)
>import foo_highlighting
>
># General configuration
># -
>
># Add any Sphinx extension module names here, as strings. They can be
># extensions
># coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
>extensions = ['foo_highlighting']
>
> And you should be good to go (if your lexer is useful send it to the
> Pygments
> guys so we can all use it :-)
>
> Gabriel
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Author field with an ampersand fails "make all-pdf"

2008-10-16 Thread Bruce Eckel
Clarification: we should use \and in the sphinx sources?

On Thu, Oct 16, 2008 at 3:43 PM, Georg Brandl <[EMAIL PROTECTED]> wrote:

>
> Sergey A. Lipnevich schrieb:
> > Hi,
> >
> > With Sphinx 0.5dev-20081015, Python 2.6, and MiKTeX-pdfTeX 2.7.3147 on
> > Windows XP, I get the following error when an Author (specified in
> > Quick Start step) contains an ampersand (e.g. "Ano & Nymous"). I've no
> > idea if the fix should be on LaTeX side (in which case I'm ready to
> > give up) or Python side (I'd appreciate a hint as to where to look for
> > a solution and will submit a patch). I can also file it on
> http://bugs.python.org/.
> > Regards,
>
> The author and title fields of the "LaTeX documents" setting are inserted
> into the output as LaTeX code. You should use "\and" to indicate more than
> one author, LaTeX will typeset that nicely then.
>
> That said, I've changed two things:
> * When entering names in quickstart, they are escaped properly, so that
>  there won't be an error when running LaTeX.
> * The docs now explicitly spell out that the values are LaTeX code.
>
> Georg
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: treetoc & indentation

2008-10-16 Thread Bruce Eckel
I agree. Once I got it working I've been really impressed with the results.
These are things I've thought of/tried to do on my own in the past, and this
is so much better than anything I tried. The default HTML is terrific (with
the built-in search!), and the Windows Help format is also great. I expect
this will be a great thing for the Python book project.
I haven't gone through the Latex->PDF process yet but I have high hopes that
I can uses that to produce camera-ready copy for books.

On Thu, Oct 16, 2008 at 11:08 AM, Alessandro Dentella <[EMAIL PROTECTED]>wrote:

>
> > I'm glad you found the solution -- I didn't have much time lately to
> > answer questions. This should change now, since my exams are over for
> > this term, and I can finally devote more time to hacking and improving
> > Sphinx again :)
>
>
> Don't say that too loud, I could find many other questions...
>
> By the way: writing docs with sphinx it's a real pleasure, thanks for your
> job. I turned into sphinx-based all my documentation sites.
>
> sandro
> *:-)
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Followed instructions, getting errors

2008-10-13 Thread Bruce Eckel
For what it's worth, here's one way to change encodings. I'm just thrashing
around here so there may be a more elegant way:
#! /usr/bin/env python
import os, codecs

for root, dirs, files in os.walk("book"):
for f in files:
if f.endswith(".txt"):
path = os.path.join(root, f)
fileObj = codecs.open(path, "r", "latin-1")
u = fileObj.read() # Returns a Unicode string from the latin-1
bytes in the file
file(path, 'w').write(u.encode("utf-8", 'replace'))

On Mon, Oct 13, 2008 at 11:09 AM, Bruce Eckel <[EMAIL PROTECTED]> wrote:

> Still trying to understand the issue: Sphinx itself will not handle
> anything but utf-8? As you say, a bit muddy -- the above looks like a
> strategy pattern which suggests that Sphinx might be able to handle more
> than one kind of encoding. But perhaps other code within Sphinx prevents
> this?
> Sorry for the confused newbie questions, everyone. Just trying to get a
> handle on all this.
>
>
> On Mon, Oct 13, 2008 at 10:26 AM, Yarko T <[EMAIL PROTECTED]> wrote:
>
>>
>>
>> On Mon, Oct 13, 2008 at 11:17 AM, Yarko T <[EMAIL PROTECTED]> wrote:
>>
>>> this is a bit muddy to me:
>>> 
>>>
>>> encoding = options.get('encoding', 'utf-8')
>>> try:
>>> f = codecs.open(fn, 'r', encoding)
>>> text = f.read()
>>> f.close()
>>>
>>> So I'll guess you can use this to filter your source files (?).
>>>
>>> Regards,
>>> Yarko
>>>
>>
>> that is to say, this strategy - create a filter based on this simple
>> I/O pattern, and run through your source tree, letting codecs do the
>> conversion...
>>
>>
>>>
>>> On Mon, Oct 13, 2008 at 12:55 AM, Bruce Eckel <[EMAIL PROTECTED]>wrote:
>>>
>>>> OK, the next question is how to make the change. The only thing I found
>>>> in the docs was a reference to the conf.py file, but changing that (to, for
>>>> example, latin-1 which should take care of it) doesn't have any effect.
>>>> Thanks for any help.
>>>>
>>>>
>>>> On Sun, Oct 12, 2008 at 8:20 PM, Peter Hoffmann <[EMAIL PROTECTED]>wrote:
>>>>
>>>>>
>>>>> The problem is the word Façade. As far as I know sphinx only supports
>>>>> utf-8 file encodings, but your file changeInterface/
>>>>> changeInterface.txt (and some others too) use non ascii characters
>>>>> with 8859 file encoding.
>>>>>
>>>>> If you change the file encoding to utf-8 and try again, it should work
>>>>> (beside some other errors due to wrong length of underline for
>>>>> headings).
>>>>>
>>>>> Regards Peter
>>>>>
>>>>>
>>>>> On 13 Okt., 03:10, "Bruce Eckel" <[EMAIL PROTECTED]> wrote:
>>>>> > I used sphinx-quickstart to get started, and I think I followed the
>>>>> > instructions correctly. I've attached my project, which gives me the
>>>>> > following error:
>>>>> > $ make html
>>>>> > mkdir -p _build/html _build/doctrees
>>>>> > sphinx-build -b html -d _build/doctrees   . _build/html
>>>>> > Sphinx v0.4.3, building html
>>>>> > trying to load pickled env... not found
>>>>> > building [html]: targets for 20 source files that are out of date
>>>>> > updating environment: 20 added, 0 changed, 0 removed
>>>>> > reading... appFrameworks/appFrameworks
>>>>> changeInterface/changeInterface
>>>>> > Exception occurred:
>>>>> >   File "C:\Python\Lib\site-packages\docutils\io.py", line 124, in
>>>>> > decode  error_details))
>>>>> > UnicodeError: Unable to decode input data.  Tried the following
>>>>> encodings:
>>>>> > 'utf-8'.
>>>>> > (UnicodeDecodeError: 'utf8' codec can't decode bytes in position
>>>>> 432-434:
>>>>> > invalid data)
>>>>> > The full traceback has been saved in
>>>>> > c:\docume~1\bruce\locals~1\temp\sphinx-err-o_ecqz.log, if you want to
>>>>> report
>>>>> > the issue to the author.
>>>>> > Please also report this if it was a user error, so that a better
>>>>> error
>>>>> > message c
>>>>> > an be provided next time.
>>>>> > Send reports to [EMAIL PROTECTED] Thanks!
>>>>> > make: *** [html] Error 1
>>>>> >
>>>>> > --
>>>>> > Bruce Eckel
>>>>> >
>>>>> >  book.zip
>>>>> > 267KAnzeigenHerunterladen
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> Bruce Eckel
>>>>
>>>>
>>>>
>>>>
>>>
>>
>> >>
>>
>
>
> --
> Bruce Eckel
>
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Followed instructions, getting errors

2008-10-13 Thread Bruce Eckel
Still trying to understand the issue: Sphinx itself will not handle anything
but utf-8? As you say, a bit muddy -- the above looks like a strategy
pattern which suggests that Sphinx might be able to handle more than one
kind of encoding. But perhaps other code within Sphinx prevents this?
Sorry for the confused newbie questions, everyone. Just trying to get a
handle on all this.

On Mon, Oct 13, 2008 at 10:26 AM, Yarko T <[EMAIL PROTECTED]> wrote:

>
>
> On Mon, Oct 13, 2008 at 11:17 AM, Yarko T <[EMAIL PROTECTED]> wrote:
>
>> this is a bit muddy to me:
>> 
>>
>> encoding = options.get('encoding', 'utf-8')
>> try:
>> f = codecs.open(fn, 'r', encoding)
>> text = f.read()
>> f.close()
>>
>> So I'll guess you can use this to filter your source files (?).
>>
>> Regards,
>> Yarko
>>
>
> that is to say, this strategy - create a filter based on this simple
> I/O pattern, and run through your source tree, letting codecs do the
> conversion...
>
>
>>
>> On Mon, Oct 13, 2008 at 12:55 AM, Bruce Eckel <[EMAIL PROTECTED]>wrote:
>>
>>> OK, the next question is how to make the change. The only thing I found
>>> in the docs was a reference to the conf.py file, but changing that (to, for
>>> example, latin-1 which should take care of it) doesn't have any effect.
>>> Thanks for any help.
>>>
>>>
>>> On Sun, Oct 12, 2008 at 8:20 PM, Peter Hoffmann <[EMAIL PROTECTED]>wrote:
>>>
>>>>
>>>> The problem is the word Façade. As far as I know sphinx only supports
>>>> utf-8 file encodings, but your file changeInterface/
>>>> changeInterface.txt (and some others too) use non ascii characters
>>>> with 8859 file encoding.
>>>>
>>>> If you change the file encoding to utf-8 and try again, it should work
>>>> (beside some other errors due to wrong length of underline for
>>>> headings).
>>>>
>>>> Regards Peter
>>>>
>>>>
>>>> On 13 Okt., 03:10, "Bruce Eckel" <[EMAIL PROTECTED]> wrote:
>>>> > I used sphinx-quickstart to get started, and I think I followed the
>>>> > instructions correctly. I've attached my project, which gives me the
>>>> > following error:
>>>> > $ make html
>>>> > mkdir -p _build/html _build/doctrees
>>>> > sphinx-build -b html -d _build/doctrees   . _build/html
>>>> > Sphinx v0.4.3, building html
>>>> > trying to load pickled env... not found
>>>> > building [html]: targets for 20 source files that are out of date
>>>> > updating environment: 20 added, 0 changed, 0 removed
>>>> > reading... appFrameworks/appFrameworks changeInterface/changeInterface
>>>> > Exception occurred:
>>>> >   File "C:\Python\Lib\site-packages\docutils\io.py", line 124, in
>>>> > decode  error_details))
>>>> > UnicodeError: Unable to decode input data.  Tried the following
>>>> encodings:
>>>> > 'utf-8'.
>>>> > (UnicodeDecodeError: 'utf8' codec can't decode bytes in position
>>>> 432-434:
>>>> > invalid data)
>>>> > The full traceback has been saved in
>>>> > c:\docume~1\bruce\locals~1\temp\sphinx-err-o_ecqz.log, if you want to
>>>> report
>>>> > the issue to the author.
>>>> > Please also report this if it was a user error, so that a better error
>>>> > message c
>>>> > an be provided next time.
>>>> > Send reports to [EMAIL PROTECTED] Thanks!
>>>> > make: *** [html] Error 1
>>>> >
>>>> > --
>>>> > Bruce Eckel
>>>> >
>>>> >  book.zip
>>>> > 267KAnzeigenHerunterladen
>>>>
>>>>
>>>
>>>
>>> --
>>> Bruce Eckel
>>>
>>>
>>>
>>>
>>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Followed instructions, getting errors

2008-10-13 Thread Bruce Eckel
I was trying to figure out how to change the sphinx configuration files so
that it would support (for example) latin-1.
Are you saying that sphinx will *only* support utf-8, and thus cannot deal
with words like Facade?

Also, is this a typical error message or do most errors in Sphinx give you
direction to the problem? (the error I got made it appear that Sphinx itself
was broken)

On Mon, Oct 13, 2008 at 2:32 AM, Jan-Philip Gehrcke
<[EMAIL PROTECTED]>wrote:

>
> Open your source file with an editor that is able to change source
> enconding and set it to utf-8. Every suitable editor should be able to
> change source enconding.
>
> Bruce Eckel wrote:
> > OK, the next question is how to make the change. The only thing I
> > found in the docs was a reference to the conf.py file, but changing
> > that (to, for example, latin-1 which should take care of it) doesn't
> > have any effect.
> >
> > Thanks for any help.
> >
> > On Sun, Oct 12, 2008 at 8:20 PM, Peter Hoffmann <[EMAIL PROTECTED]
> > <mailto:[EMAIL PROTECTED]>> wrote:
> >
> >
> > The problem is the word Façade. As far as I know sphinx only supports
> > utf-8 file encodings, but your file changeInterface/
> > changeInterface.txt (and some others too) use non ascii characters
> > with 8859 file encoding.
> >
> > If you change the file encoding to utf-8 and try again, it should
> work
> >     (beside some other errors due to wrong length of underline for
> > headings).
> >
> > Regards Peter
> >
> >
> > On 13 Okt., 03:10, "Bruce Eckel" <[EMAIL PROTECTED]
> > <mailto:[EMAIL PROTECTED]>> wrote:
> > > I used sphinx-quickstart to get started, and I think I followed the
> > > instructions correctly. I've attached my project, which gives me
> the
> > > following error:
> > > $ make html
> > > mkdir -p _build/html _build/doctrees
> > > sphinx-build -b html -d _build/doctrees   . _build/html
> > > Sphinx v0.4.3, building html
> > > trying to load pickled env... not found
> > > building [html]: targets for 20 source files that are out of date
> > > updating environment: 20 added, 0 changed, 0 removed
> > > reading... appFrameworks/appFrameworks
> > changeInterface/changeInterface
> > > Exception occurred:
> > >   File "C:\Python\Lib\site-packages\docutils\io.py", line 124, in
> > > decode  error_details))
> > > UnicodeError: Unable to decode input data.  Tried the following
> > encodings:
> > > 'utf-8'.
> > > (UnicodeDecodeError: 'utf8' codec can't decode bytes in position
> > 432-434:
> > > invalid data)
> > > The full traceback has been saved in
> > > c:\docume~1\bruce\locals~1\temp\sphinx-err-o_ecqz.log, if you
> > want to report
> > > the issue to the author.
> > > Please also report this if it was a user error, so that a better
> > error
> > > message c
> > > an be provided next time.
> > > Send reports to sphinx-dev@googlegroups.com
> > <mailto:sphinx-dev@googlegroups.com>. Thanks!
> > > make: *** [html] Error 1
> > >
> > > --
> > > Bruce Eckel
> > >
> > >  book.zip
> > > 267KAnzeigenHerunterladen
> >
> >
> >
> >
> > --
> > Bruce Eckel
> >
> >
> > >
>
>
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---



Re: Followed instructions, getting errors

2008-10-12 Thread Bruce Eckel
OK, the next question is how to make the change. The only thing I found in
the docs was a reference to the conf.py file, but changing that (to, for
example, latin-1 which should take care of it) doesn't have any effect.
Thanks for any help.

On Sun, Oct 12, 2008 at 8:20 PM, Peter Hoffmann <[EMAIL PROTECTED]> wrote:

>
> The problem is the word Façade. As far as I know sphinx only supports
> utf-8 file encodings, but your file changeInterface/
> changeInterface.txt (and some others too) use non ascii characters
> with 8859 file encoding.
>
> If you change the file encoding to utf-8 and try again, it should work
> (beside some other errors due to wrong length of underline for
> headings).
>
> Regards Peter
>
>
> On 13 Okt., 03:10, "Bruce Eckel" <[EMAIL PROTECTED]> wrote:
> > I used sphinx-quickstart to get started, and I think I followed the
> > instructions correctly. I've attached my project, which gives me the
> > following error:
> > $ make html
> > mkdir -p _build/html _build/doctrees
> > sphinx-build -b html -d _build/doctrees   . _build/html
> > Sphinx v0.4.3, building html
> > trying to load pickled env... not found
> > building [html]: targets for 20 source files that are out of date
> > updating environment: 20 added, 0 changed, 0 removed
> > reading... appFrameworks/appFrameworks changeInterface/changeInterface
> > Exception occurred:
> >   File "C:\Python\Lib\site-packages\docutils\io.py", line 124, in
> > decode  error_details))
> > UnicodeError: Unable to decode input data.  Tried the following
> encodings:
> > 'utf-8'.
> > (UnicodeDecodeError: 'utf8' codec can't decode bytes in position 432-434:
> > invalid data)
> > The full traceback has been saved in
> > c:\docume~1\bruce\locals~1\temp\sphinx-err-o_ecqz.log, if you want to
> report
> > the issue to the author.
> > Please also report this if it was a user error, so that a better error
> > message c
> > an be provided next time.
> > Send reports to [EMAIL PROTECTED] Thanks!
> > make: *** [html] Error 1
> >
> > --
> > Bruce Eckel
> >
> >  book.zip
> > 267KAnzeigenHerunterladen
> >
>


-- 
Bruce Eckel

--~--~-~--~~~---~--~~
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 [EMAIL PROTECTED]
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en
-~--~~~~--~~--~--~---