Re: [sphinx-dev] Auto generate links to sections
On Thu, Oct 4, 2012 at 1:40 PM, RBH Dev wrote: > At the top of my HTML generated files, I'd like to have a table of contents > of all sections of the current page. How do I do that? And can I add a > back to top button at the end of each section? See [1] which points to [2]. [1] http://sphinx.pocoo.org/markup/para.html#table-of-contents-markup [2] 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-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] Word-wrap in code-block?
On Thu, Aug 16, 2012 at 8:10 AM, Boris Kheyfets wrote:
> Is it possible to impose a word-wrap in code-block?
For HTML, I do something like the following in the theme's css file:
pre {
white-space: pre-wrap;
}
--
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: Sidebar Table of Contents Should Cover the Entire Doc Set, Not Just the Headings on the Current Page
On Tue, Aug 7, 2012 at 7:34 AM, Viktor Haag wrote: > This of course only helps people that are using a theme that supports > html_sidebars. My docs use ..contents:: to put in floating page-only TOCs, > and I like that. Having a way to also provide a "table of contents" page > that would be the globaltoc would be useful, too. Huh? That's exactly what the toctree directive [1] is for. Right? [1] http://sphinx.pocoo.org/markup/toctree.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-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] Sidebar Table of Contents Should Cover the Entire Doc Set, Not Just the Headings on the Current Page
On Thu, Jul 26, 2012 at 7:37 PM, Chris Boorman wrote: > I'm using Sphinx to help me generate docs for a Python API, and I can't find > a way to generate a complete Table of Contents. I can only get Sphinx to > auomatically generate entries for the the current page. Since my pages > aren't long, this produces short-sighted, practically useless TOCs. I need > to find a way to generate a "master" TOC that lists every topic in the > documentation set, and that can serve as a content navigation aid. Any ideas > out there? That what the globaltoc.html is for. See [1] [1] http://sphinx.pocoo.org/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-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 show ''' (triple-single quote)?
On Thu, Jun 28, 2012 at 1:15 PM, Kevin Hunter wrote: > The final one gets what I want, but man that's ugly. Do I just live with it > or is there a "cleaner" avenue? Maybe you can at least use a substitution [1] to hide the ugliness? [1] http://sphinx.pocoo.org/rest.html?highlight=substitution#substitutions -- 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] format-specific output
On Wed, Jun 27, 2012 at 1:18 AM, Kevin Hunter wrote: > Hullo Sphinx List, > > I believe I have a case where I need specific content based on the final > output format. Is there a way to tell Sphinx to only use a certain section > of the ReST document based on the final output format? > > My problem is that I have a necessarily long line of pre-formatted text > (code example). This is no problem for HTML where the browser will simply > show a scrollbar and the user can see what they need to. However, for PDF > output (latexpdf), the line does not wrap, and therefore gets' cut off at > the page boundary. For the PDF case, I'd like to supply an alternate > version with a minor comment about the formatting difference. I think you want the "only" directive? See [1] for more info. [1] http://sphinx.pocoo.org/markup/misc.html#including-content-based-on-tags -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Add JavaScript to every generated page
On Fri, Jun 22, 2012 at 5:59 AM, Tobias Oberstein wrote: > Is there a way to add some JS to $(document).ready() for every page > generated by Sphinx via configuration (thus avoid patching the generated > stuff afterwards)? You can do this by using the *basic* theme's *extrahead* "block". See [1] for details. [1] http://sphinx.pocoo.org/templating.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-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 do I use output a config value in my .rst files?
On Sun, Apr 22, 2012 at 6:14 AM, Doug Hellmann wrote: > In your case, you probably want to build a custom role processor Or perhaps use the standard sphinx.ext.extlinks extension [1]. [1] http://sphinx.pocoo.org/ext/extlinks.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-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: disable search
On Tue, Mar 6, 2012 at 4:47 AM, Rita Morgan wrote:
> Thanks for your reply.
>
> I made a change in my config.py
>
> # Custom sidebar templates, maps document names to template names.
> #html_sidebars = {}
> html_sidebars = {'localtoc.html'}
>
> Then I do a make html and I get the following message
>
> Running Sphinx v1.0.1
> loading pickled environment... done
> building [html]: targets for 1 source files that are out of date
> updating environment: 0 added, 0 changed, 0 removed
> looking for now-outdated files... none found
> preparing documents... done
> writing output... [100%]
> index
> Exception occurred:
> File "/usr/lib/pymodules/python2.7/sphinx/builders/html.py", line
> 644, in add_sidebars
> for pattern, patsidebars in self.config.html_sidebars.iteritems():
> AttributeError: 'set' object has no attribute 'iteritems'
> The full traceback has been saved in /tmp/sphinx-err-AZLTXh.log, if
> you want to report the issue to the developers.
> Please also report this if it was a user error, so that a better error
> message can be provided next time.
> Either send bugs to the mailing list at <http://groups.google.com/
> group/sphinx-dev/>,
> or report them in the tracker at <http://bitbucket.org/birkenfeld/
> sphinx/issues/>. Thanks!
> make: *** [html] Error 1
>
>
>
>
>
> On Mar 4, 6:56 pm, TP wrote:
>> On Sat, Mar 3, 2012 at 9:07 PM, Rita wrote:
>> > How can I disable the search box? It doesnt seem to work.
>>
>> Seehttp://sphinx.pocoo.org/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-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.
>
Since the example says do this:
html_sidebars = {
'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
'using/windows': ['windowssidebar.html', 'searchbox.html'],
}
I assume you should do:
html_sidebars = {
'**': ['localtoc.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-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] disable search
On Sat, Mar 3, 2012 at 9:07 PM, Rita wrote: > How can I disable the search box? It doesnt seem to work. See http://sphinx.pocoo.org/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-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] inject data into a document
On Sat, Mar 3, 2012 at 7:25 AM, Rita wrote: > Hello, > > I am building a HTML table which is in a file and I would like to inject > that into my rst file. Is it possible to include that into a document? See http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through -- 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] Add Creative Commons license instead of Copyright?
On Sun, Nov 20, 2011 at 7:35 PM, Kristina Hoeppner
wrote:
> Hello,
>
> I started to write the Mahara documentation (http://manual.mahara.org)
> in rst last week and we use Sphinx to publish it to Read the Docs.
> Most things work great. :-)
>
> Is it possible to exchange the standard copyright notice for a
> Creative Commons license in the footer of the documents? As we are
> using the Sphinx converter on Read the Docs we can't make changes that
> can't be placed in conf.py or another content / theme file.
>
> Thanks
> Kristina
I do that by putting something like the following in layout.html. See
http://sphinx.pocoo.org/templating.html for details on layout.html
(and how to override the footer).
{%- block footer %}
http://creativecommons.org/licenses/by/3.0/us/"; >
Whatever is licensed under a
http://creativecommons.org/licenses/by/3.0/us/";>
Creative Commons Attribution 3.0 United States License.
{%- 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-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] Paragraphs in Lists
On Tue, Nov 1, 2011 at 7:07 PM, Friedrich Romstedt wrote: > The following rst snipped causes some trouble. I see and appreciate the > mechanism that "complex" or rather "complex enough" list items are rendered > using paragraphs and so all list items, the problem is, that does not apply > to contained (and as well, I think) in Sphinx at least. Don't > know if that is a Sphinx or a docutils issue. I feel this as an issue, > since the rst input and the html output do not match in visual alignment. Did you try setting html_compact_lists (http://sphinx.pocoo.org/config.html#confval-html_compact_lists) to False in your conf.py file? I suggested this option a year or so ago to make lists consistent regardless of whether they were complex or not. You can then adjust your .css file to get whatever spacing you want. -- 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] using file targets/abbrevs in a table
On Tue, May 24, 2011 at 12:37 PM, Philip Austin wrote: > (pre-question: anyone know how to get a plain textbox for posting? > I've tried to attach the actual rst file in case spacing get corrupted > by the non-wysiwyg widget) > > I'm trying to automate the production of tables containing large numbers > (hundreds) of figures. It would help readability if I could abbreviate the > figure > path in some way, using targets or string replacements like this: > > .. _fig1: //home/xwei/public_html/results/docs/new/GCM/cld-anom-cccma.png > .. |fig1| replace:: > //home/xwei/public_html/results/docs/new/GCM/cld-anom-cccma.png > > However, although this works: > > +---+--+ > | model | CCCma > | > +---+--+ > | total cld | .. figure:: > //home/xwei/public_html/results/docs/new/GCM/cld-anom-cccma.png | > | | :scale: 30 > | > +---+--+ > > these two fail, with the message: > > /nfs/kite/home/phil/public_html/imagetest/index.rst:: WARNING: image file > not readable: `fig1`_ > /nfs/kite/home/phil/public_html/imagetest/index.rst:: WARNING: image file > not readable: |fig1| > > +--+--+ > | model | > CCCma > | > +--+--+ > | total cld | .. figure:: `fig1`_ > | > | | :scale: 30 > | > +--+--+ > > +--+--+ > | model | > CCCma > | > +--+--+ > | total cld | .. figure:: |fig1| > | > | | :scale: 30 > | > +--+--+ > > Is there a syntax/feature I'm missing? thanks, Phil > > -- > 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. > Dunno if this is applicable to your problem but you might want to look at the extlinks extension documented at: http://sphinx.pocoo.org/ext/extlinks.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-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 would you include huge tables?
On Wed, May 25, 2011 at 11:59 AM, Kevin Horn wrote: > > > On Wed, May 25, 2011 at 12:44 PM, Jan Ulrich Hasecke > wrote: >> >> -BEGIN PGP SIGNED MESSAGE- >> Hash: SHA1 >> >> Hi, >> >> I want to include huge tables in my sphinx project. The data is in a >> spreadsheet. I can save the spreadsheets as html via LibreOffice or as >> CSV, but how can I convert these html-tables to rst-tables? >> >> I don't need the tables in the text, but as an appendix so maybe there >> is a better solution? >> >> - -- >> Jan Ulrich Hasecke >> DZUG e.V. (Deutschsprachige Zope User Group) >> -BEGIN PGP SIGNATURE- >> Version: GnuPG v1.4.10 (Darwin) >> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ >> >> iEYEARECAAYFAk3dP+4ACgkQPUzUEFbILMSugQCgnF2s2Y6FGSPIWIjg1tGLf1dg >> S6sAn05MxQyVotJU+4DdmmU4sX+Mc+gh >> =8gMq >> -END PGP SIGNATURE- >> > > I use some code to parse the data and create rst tables. > > See: > http://media.commandline.org.uk/code/table.txt > and > https://bitbucket.org/khorn/lore2sphinx/src/7b0939832687/lore2sphinx/table.py > > Kevin Horn > > -- > You received this message because you are subscribed to the Google Groups > "sphinx-dev" group. > To post to this group, send email to sphinx-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. > I've never used it but docutils (upon which Sphinx is based) already has support for "CSV Tables". See http://docutils.sourceforge.net/docs/ref/rst/directives.html#id1 for details. --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-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] Where's the documentation for :source: ?
On Thu, Mar 17, 2011 at 4:20 AM, cool-RR wrote: > On Thu, Mar 17, 2011 at 3:25 AM, werner wrote: >> >> Ram, >> >> On 17/03/2011 01:53, cool-RR wrote: >>> >>> Hello, >>> >>> I see that the new Python docs are able to link to source files in the >>> Python hg repo, like in here: >>> >>> http://docs.python.org/dev/library/abc.html >>> >>> This is very cool. I see that this is done with the :source: role, but I >>> was unable to find the docs for it. Where are they? >>> >> I believe it uses this extension. >> >> http://sphinx.pocoo.org/ext/viewcode.html?highlight=configuration >> >> Werner > > I don't think so. The Python docs link to the SVN repo (which redirects to > HG), not to a Sphinx-created source-displaying HTML file. > > -- > 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. > Maybe it is using the extlinks extension documented at http://sphinx.pocoo.org/ext/extlinks.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-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] Beginner's Guide?
On Mon, Feb 21, 2011 at 8:08 AM, werner wrote: > On 21/02/2011 16:44, TP wrote: >> >> For one example of how to document a Python method see >> >> http://tpgit.github.com/MDIImageViewer/imageviewer.html#imageviewer.ImageViewer.scaleImage. >> Click on the [source] link on the right to see the actual Python >> method (along with its docstring that generated the documentation). >> > What causes the Inheritance diagram to go top/down instead of right/left? > Is this some conf.py setting or ...? > > I am working on documenting Dabo with Sphinx and if you look at this page > you can see my problem with the inheritance diagram. > > http://thewinecellarbook.com/daboDocTest/dabo.ui.dButton.dButton.html > > Werner > > -- > 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. > > In my conf.py I have: inheritance_graph_attrs = dict(rankdir="TB") Use of which is mentioned at http://sphinx.pocoo.org/ext/inheritance.html#confval-inheritance_graph_attrs rankdir is somewhat documented at http://graphviz.org/doc/info/attrs.html#d:rankdir. -- 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-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] Beginner's Guide?
On Fri, Feb 18, 2011 at 5:00 AM, Burhan wrote: > Hello: > > I am new to Sphinx, and am going to use it for a python project to > generate HTML documentation. My problem is rather basic, I'm not sure > how to format my docstrings so that Sphinx can extract the > information. > > I understand about using autodoc extension, and making sure that my > modules are available to python so that sphinx can find my code - my > problem is a bit basic, how do I actually comment the code? > > Do I have to enter *verbatim* examples are written in the > documentation? So for example, is it like this: > > def my_funct(param=None,param2=None): > """ > .. py:func:: my_funct(param=None,param2=None) > This function does something with two parameters, > which are default to :py:`None` > """ > > Or do I have to document it separately in another file? A simple > python code example would really help me out. > > Thanks. > > -- > 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. > > The basic idea is that you just use "info field lists" (http://sphinx.pocoo.org/domains.html?highlight=info%20field%20lists#info-field-lists) to document function parameters directly in your docstrings. If you need more details, I wrote a fairly simple PyQt app called MDIImageViewer and one of its goals was to demonstrate how to document Python projects using Sphinx. You can find the generated HTML documentation at: http://tpgit.github.com/MDIImageViewer. Clicking on the "Show Source" link on any page will show you the Sphinx .rst source for that page. http://tpgit.github.com/MDIImageViewer/implementation.html#sphinx-documentation-notes briefly discusses how I used Sphinx to generate the documentation. The Python sources are at: http://github.com/tpgit/MDIImageViewer/archives/master, The Sphinx .rst files are at http://github.com/tpgit/MDIImageViewer/tree/master/sphinx/. For one example of how to document a Python method see http://tpgit.github.com/MDIImageViewer/imageviewer.html#imageviewer.ImageViewer.scaleImage. Click on the [source] link on the right to see the actual Python method (along with its docstring that generated the documentation). -- 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-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] Fwd: autodoc, ¿config?
2011/1/14 slothy Rulez a lot : > Hi! > I'm newbie using sphinx, it looks pretty good, I have almost documented all > my proyect using autodoc, but I want to change one behavior, reading > documentation, i've seen > this, http://sphinx.pocoo.org/ext/autodoc.html#confval-autodoc_member_order, > and want to change to 'bysource' value, the point is, where is supposed to > put this value? > Using Sphinx 0.6.6 > Thanks, and apologise for my poor english. > Slothy > > -- > 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 add autodoc_member_order to your conf.py file. Or you can add the :member-order: option to your automodule or autoclass directive. But from the documentation it looks like the "bysource" value is only supported for Sphinx 1.x+ not 0.6.6. -- 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 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] Two newbie questions
On Thu, Jan 13, 2011 at 9:32 AM, Curiouslearn 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:
...
Some text that uses my custom role.
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 wrote:
>> 2011/1/13 Curiouslearn
>>>
>>> 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
>> # " v 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] how to share documents created using Sphinx (html version)
On Thu, Jan 13, 2011 at 11:18 AM, Curiouslearn 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] Possible to break a title across two lines?
On Thu, Jan 13, 2011 at 9:35 AM, Curiouslearn 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:
This is My Very Long Subtitle
That Spans Two Lines By Using a <br />
After rereading the above mentioned documentation on "container", I
see that I should probably have done the following:
.. container:: subtitle
Which generates the clearer:
> Thanks for your patience.
>
>
> On Thu, Jan 13, 2011 at 7:28 AM, TP wrote:
>> On Thu, Jan 13, 2011 at 2:07 AM, Curiouslearn 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 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| replace:: :raw-html:``
>>
>> 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] Possible to break a title across two lines?
On Thu, Jan 13, 2011 at 2:07 AM, Curiouslearn 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 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| replace:: :raw-html:`` 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.
Re: [sphinx-dev] Re: |release| substitution inside a download link
On Wed, Nov 17, 2010 at 3:16 AM, qx guy wrote: > > > On Nov 11, 8:34 am, TP 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
On Wed, Nov 10, 2010 at 4:08 AM, qx guy 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] How is the Sphinx home page created?
On 10/21/10, TP wrote:
> On 10/21/10, SHIBUKAWA Yoshiki 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] How is the Sphinx home page created?
On 10/21/10, SHIBUKAWA Yoshiki 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.
[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] sphinx.ext.autodoc
On Thu, Oct 21, 2010 at 8:39 AM, Jacob Kaplan-Moss wrote: > On Thu, Oct 21, 2010 at 10:09 AM, Maarch 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.
Re: [sphinx-dev] accessing global variables like 'toc'
On Mon, Sep 27, 2010 at 4:14 AM, Alastair Dent 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] html in docs
On Thu, Sep 23, 2010 at 12:54 PM, Jeremy wrote:
> Hello,
> I'm new to Sphinx and was wondering if there is a way to render
> html that was typed in rst?
>
> Something along the lines of this:
>
> .. sourcecode:: html
> My Div
>
>
> The above would actually render a div in the docs when built.
>
> I would also like to do the following:
>
> .. sourcecode: javascript
> alert('hi')
>
> And this will present the viewer of the docs with an alert box.
>
> Is there currently a way to do this? If not is there any direction
> someone could give me on editing the markup rendered via a custom
> built extension.
>
> I have already created one extension and am slowly getting familiar
> with the code, but at this point I'm unable to see anyway of rendering
> the above.
>
> Thank you,
> Jeremy
>
> --
> 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.
>
>
Did you try the "raw" directive?
See http://sphinx.pocoo.org/rest.html#directives and
http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw for
more info.
--
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
On Wed, Aug 25, 2010 at 12:12 AM, TP wrote: > On Tue, Aug 24, 2010 at 4:04 PM, Fernando Perez wrote: >> On Tue, Aug 24, 2010 at 2:58 PM, Kevin Dunn 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, >> >> 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. >> >> > > 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 > 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 tag in order for Internet Explorer 8 not to be ridiculously slow when displaying pages with MathJax (even only small amounts): 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 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. -- 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
On Tue, Aug 24, 2010 at 4:04 PM, Fernando Perez wrote: > On Tue, Aug 24, 2010 at 2:58 PM, Kevin Dunn 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, > > 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. > > 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 -- 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 do you prevent SmartyPants from changing single-quote character?
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
On Tue, Aug 17, 2010 at 2:25 PM, David 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: rm is strong 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
On Fri, Apr 16, 2010 at 8:57 AM, gslindstrom 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
On Mon, Apr 19, 2010 at 4:10 AM, mark 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/4/13 Václav Šmilauer : > 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 ?
On Mon, Apr 12, 2010 at 11:17 AM, Michael Rule 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 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 wrote: >>> On Mon, Apr 12, 2010 at 8:33 AM, Michael Rule 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] how to turn off alphabetical ordering ?
On Mon, Apr 12, 2010 at 8:33 AM, Michael Rule 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] Multiple stylings of preformatted text
On Fri, Apr 9, 2010 at 12:17 AM, TP wrote: > On Thu, Apr 8, 2010 at 11:34 PM, malthe 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. > Ooops. I should also have mentioned this: http://sphinx.pocoo.org/markup/desc.html#dir-class "New in version 0.4: The standard reST directive class is now provided by Sphinx under the name cssclass." -- 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
On Thu, Apr 8, 2010 at 11:34 PM, malthe 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
On Thu, Apr 8, 2010 at 7:30 AM, Jan Ulrich Hasecke
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] Flash animation in Sphinx output?
On Tue, Apr 6, 2010 at 8:55 PM, Grammarian wrote: > How can I embed a Flash animation into documentation produced by > Sphinx? Offhand, I say use the "raw" directive (http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through), and do whatever it is you do in normal 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] ReStructuredTextToolsForGedit
On Mon, Mar 29, 2010 at 11:48 PM, werner 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] toctree() does not work if there is just one section per file
On Fri, Apr 2, 2010 at 9:46 AM, Nikolaus Rath wrote:
> Hello,
>
> I am using
>
> {%- if display_toc %}
> {{ _('Table Of Contents')
> }}
> {{ toctree() }}
> {%- endif %}
>
> to display a table of contents in the sidebar. This works nicely in most
> cases. However, if a document has only one section, the tree is missing
> entirely.
>
> Example: http://s3ql.googlecode.com/svn/trunk/doc/html/index.html
> If you click on e.g. "Installation", there is a tree on the right. If
> you click on "Mounting", there isn't.
>
> Anyone able to help?
>
> I'm using sphinx 0.6.2.
>
> Best,
>
> -Nikolaus
>
> --
> »Time flies like an arrow, fruit flies like a Banana.«
>
> PGP fingerprint: 5B93 61F8 4EA2 E279 ABF6 02CF A9AD B7F8 AE4E 425C
>
> --
> 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 ran into this also (with latest development version). Seems this is
the designed behavior. Looking at sphinx/builders/html.py I see the
following in def get_doc_context(self, docname, body, metatags):
return dict(
parents = parents,
prev = prev,
next = next,
title = title,
meta = meta,
body = body,
metatags = metatags,
rellinks = rellinks,
sourcename = sourcename,
toc = toc,
# only display a TOC if there's more than one item to show
display_toc = (self.env.toc_num_entries[docname] > 1),
)
So, all I did was remove the surrounding
{%- if display_toc %}
{%- endif %}
and things work as expected.
--
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
On Thu, Apr 1, 2010 at 3:28 PM, TP wrote:
> On Thu, Apr 1, 2010 at 8:21 AM, Paulette 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 %}
> http://openmdao.org";>OpenMDAO Home{{ reldelim1 }}
> {{ super() }}
> {% endblock %}
>
> {% block sidebarlogo %}
> http://openmdao.org"; src="{{
> pathto("_static/OpenMDAOLogo_200x56.png", 1) }}" border="0"
> alt="OpenMDAO Home"/>
> {% endblock %}
>
Oops. Should have been:
{% block sidebarlogo %}
http://openmdao.org";>
{% 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
On Thu, Apr 1, 2010 at 8:21 AM, Paulette 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 %}
http://openmdao.org";>OpenMDAO Home{{ reldelim1 }}
{{ super() }}
{% endblock %}
{% block sidebarlogo %}
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] ePub builder
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 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
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 wrote: > On Mon, Mar 29, 2010 at 2:42 PM, TP 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.
Re: [sphinx-dev] Re: ReStructuredTextToolsForGedit
I use emacs and rst.el. On Mon, Mar 29, 2010 at 1:21 PM, Tim Michelsen wrote: >> I was wondering what type of editor everyone uses for editing Sphinx rst >> files. I've spent a great deal of time perusing the internet finding a ton >> of different things including some WYSIWYG editors. > on Windows Ulipad has a similar functionality. > > Geany at least recognises RST outlines such as headlines... > > Unfortunately, I haven't found a RST markup plugin for Eclipse. > > Did anyone of you? > > -- > 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
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 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.
[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.
[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.
[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] Modifying docututils HTMLTranslator() behavior
In order to turn off docutils HTML compact-list behavior (simulate passing --no-compact-lists on the rst2html command line), I do the following in sphinx/builders/__init__.py Builder.build(), right before the environment is pickled: if self.config.html_compact_lists: self.env.settings['compact_lists'] = 1 else: self.env.settings['compact_lists'] = 0 This seems kludgy to me. Is there a better way to override docutils/writers/html4css1/__init__.py's HTMLTranslator(nodes.NodeVisitor) behavior? -- 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] Adding a custom section number suffix
In the lastest trunk revision of Sphinx, when section numbers are turned on via:
.. toctree::
:numbered:
They look like
1. Section
1.1. Subsection
In my opinion this looks ugly. I'd rather have:
1 Section
1.1 Subsection
Here's some changes that allow you to specify a custom section number
suffix just by adding the following line to the conf.py file:
secnumber_suffix = u'\u00a0\u00a0' #\u00a0 is non-break space
In sphinx/config.py add the following line somewhere inside the
config_values = dict() initialization:
secnumber_suffix = ('. ', 'html'), #By default, use original suffix.
In sphinx/writers/html.py, make the following changes to class
HTMLTranslator(BaseTranslator):
def __init__(self, builder, *args, **kwds):
...
self.secnumber_suffix = builder.config.secnumber_suffix
def visit_reference(self, node):
...
if node.hasattr('secnumber'):
self.body.append(('%s' + self.secnumber_suffix) %
'.'.join(map(str, node['secnumber'])))
def add_secnumber(self, node):
if node.hasattr('secnumber'):
self.body.append('.'.join(map(str, node['secnumber'])) +
self.secnumber_suffix)
elif isinstance(node.parent, nodes.section):
anchorname = '#' + node.parent['ids'][0]
if anchorname not in self.builder.secnumbers:
anchorname = '' # try first heading which has no anchor
if anchorname in self.builder.secnumbers:
numbers = self.builder.secnumbers[anchorname]
self.body.append('.'.join(map(str, numbers)) +
self.secnumber_suffix)
In order to make the resulting HTML look better I found the following
CSS changes also helpful (assuming the "default" theme and
globaltoc.html in the sidebar):
@import url("default.css");
div.sphinxsidebar ul,
div.sphinxsidebar ul.want-points {
list-style: none;
padding-left: 1.5em;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
list-style: none;
padding-left: 0;
}
div.sphinxsidebarwrapper li {
text-indent: -2em;
}
div.sphinxsidebar a.current {
color: yellow;
}
With section numbering turned on, you really don't need bullets.
Unless you mess with the text-indent and padding-left, long section
titles wrap underneath the section numbers. The above CSS therefore
tries to simulate "hanging-indents".
Caveat: I've only tested on a few cases, and I'm not very familiar
with sphinx... but the changes work for me.
--
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] Don't include "source" (i.e. restructured text files) in HTML output.
On Mon, Mar 22, 2010 at 2:55 PM, Warren Weckesser wrote: > Is it possible to prevent the restructured text sources from being included > in the HTML generated by Sphinx? Currently I get the restructured text > copied to a _sources directory, and the HTML files have links to these--the > left side bar has a "Show Source" link under the heading "This Page". I > don't need this, and I'd prefer to eliminate the link in the HTML and to not > copy the restructured text. > > Thanks, > > Warren > > > -- > 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. > In conf.py set "html_copy_source" to False. Also set "html_show_sourcelink" to False. See http://sphinx.pocoo.org/config.html#options-for-html-output for details. -- 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] Missing plugin warning...
On Mon, Mar 22, 2010 at 11:58 AM, TP wrote: > On Sun, Mar 21, 2010 at 6:06 AM, jelkner wrote: >> I'm using Sphinx to markup a Python textbook: >> >> http://www.openbookproject.net/thinkcs/python/english2e >> >> I'm using svg illustrations using markup like this: >> >> .. image:: illustrations/state.svg >> :alt: State diagram >> >> which generates the following html: >> >> > src="_images/state.svg" type="image/svg+xml" /> >> >> This works very well, but it seems to generate an annoying (though >> safely ignored) warning from firefox every time you visit the page: >> >> Additional plugins are required to display all the media on this >> page. [Install Missing Plugins...] >> >> My assumption is that the warning will go away in later versions of >> firefox, as the object tag becomes better supported. Is that correct? >> >> Thanks! >> >> jeff elkner >> >> -- >> 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. >> >> > > Nice book (and I like the philosophy behind the site)! > > I just started to use Sphinx, and was wondering how you got the main > page to display Table of Contents entries with only the Chapter > numbers linked, and the actual chapter titles in italic? > > And do you have the .rst sources available somewhere. It looks like > the book would not only help beginning Python programmers but also > beginning Sphinx users :) > BTW, I just tried a small test .rst file with an SVG gotten from the SVG 1.2 Tiny Test Suite (http://www.w3.org/Graphics/SVG/WG/wiki/Test_Suite_Overview#SVG_1.2_Tiny_Test_Suite). Using Firefox 3.6 I had no problems or messages with any of the basic w3 tests I tried or my small Sphinx generated test HTML. It seems you only really need an or an tag. But having both doesn't seem to hurt. Also works in Google Chrome 4.1 (but of course not IE8 which can't handle SVG without a plugin). So maybe you just need the latest Firefox for this to work correctly. -- 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] Missing plugin warning...
On Sun, Mar 21, 2010 at 6:06 AM, jelkner wrote: > I'm using Sphinx to markup a Python textbook: > > http://www.openbookproject.net/thinkcs/python/english2e > > I'm using svg illustrations using markup like this: > > .. image:: illustrations/state.svg > :alt: State diagram > > which generates the following html: > > src="_images/state.svg" type="image/svg+xml" /> > > This works very well, but it seems to generate an annoying (though > safely ignored) warning from firefox every time you visit the page: > > Additional plugins are required to display all the media on this > page. [Install Missing Plugins...] > > My assumption is that the warning will go away in later versions of > firefox, as the object tag becomes better supported. Is that correct? > > Thanks! > > jeff elkner > > -- > 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. > > Nice book (and I like the philosophy behind the site)! I just started to use Sphinx, and was wondering how you got the main page to display Table of Contents entries with only the Chapter numbers linked, and the actual chapter titles in italic? And do you have the .rst sources available somewhere. It looks like the book would not only help beginning Python programmers but also beginning Sphinx users :) -- 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.
