Re: [sphinx-dev] Re: equations references across files
On Sat, Jan 7, 2012 at 9:10 PM, Fernando Perez fperez@gmail.com wrote: 2012/1/7 Ondřej Čertík ondrej.cer...@gmail.com: So I think that is doable. I think the only problem is with: * equations and section references * literature (bibtex), especially accross files However, it just occured to me, that almost all of the problems could be fixed by simply merging all the .rst files into one by my own script, and only then giving it to Sphinx. Then the only problem to fix is: * bibtex * modify the latex template so that the thesis conforms to the school format requirements. I think that's what I'll do. True, and it may be the right solution for you. Though it would be great if instead of needing manual post-processing with extra tools, this was possible out of the box in sphinx. It's trivial to export an ipython notebook to rst, so if these things were possible within sphinx, the combination of sphinx and ipython would make it very, very easy to create complex documents like your book or a thesis but with sections that have code and plots produced from notebooks. All you'd need is in your makefile to have a rule %.rst : %.ipynb ipython nbexport --sphinx $ [ note, right now 'ipython nbexport' doesn't really exist, but the basics are just this: https://gist.github.com/1569580 and we'll have it soon in a more clean implementation] Your sphinx project could then consist of a mixture of hand-written .rst files and ipynb ones for the compute-heavy stuff. I hope to be able to somehow import the .rst file, possibly with some specific .rst hints, like .. ipynb::. Obviously one could carry around your script as an extra tool, but the more this works out of the box, the easier gaining widespread adoption it will be. Still, do let us know how it goes and please do post any additional tools you develop for this; we're likely to reuse them :) Definitely. I can promise that I will try to use sphinx and do my best to make it work (given my timeframe) for my job. If nothing, just having it in .rst makes it easy for me to reuse most parts of it and simply add it to my book. I now routinely use SymPy in the book, just an example from a few days ago: http://theoretical-physics.net/dev/src/math/groups.html#example-i Scroll a few pages for the longer script + output. I would love to make this interactive using the ipython notebook eventually. Hopefully it will not be too much work to port all sympy/python examples into some interactive form. However, I need to figure out how to make sphinx produce solid results in latex, so that the printed version of the book looks professional. Ondrej -- 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: equations references across files
2012/1/8 Ondřej Čertík ondrej.cer...@gmail.com: I now routinely use SymPy in the book, just an example from a few days ago: http://theoretical-physics.net/dev/src/math/groups.html#example-i Scroll a few pages for the longer script + output. I would love to make this interactive using the ipython notebook eventually. Neat! Hopefully it will not be too much work to port all sympy/python examples into some interactive form. Indeed, it's very easy. You can import any .py file into the notebook by dragging it into the dashboard file area. If it's a simple script it becomes one big cell, but it's very easy to put cell markers in the .py file yourself to ease the initial import. The following is the minimal script that will import correctly as a notebook, nicely split into cells: # nbformat2/nbformat # codecell A simple cell with a docstring # markdowncell # Some text in a markdown cell # codecell # A cell with code def f(x): return x # codecell # Another cell with code def g(x): pass etc... So: take your sympy examples, add the format marker at the top and then put # codecell markers where you want them, and presto! Sympy notebooks that you can then export in your makefile back to rST. Just put the ipynb-rst rule in your makefile and use the exporter in the gist I pointed above for now; we'll add a clean version of that to ipython soon. However, I need to figure out how to make sphinx produce solid results in latex, so that the printed version of the book looks professional. Certainly! Best of luck, this is excellent work and will be super useful. 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-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.
[sphinx-dev] Re: equations references across files
On 2012-01-08, Ondřej Čertík wrote:
On Fri, Jan 6, 2012 at 3:22 PM, Fernando Perez fperez@gmail.com wrote:
2012/1/6 Ondřej Čertík ondrej.cer...@gmail.com:
...
are the other parts of writing a thesis/book with sphinx working OK
for you? I'm thinking:
- labeled references for other elements besides equations, such as saying
as we discuss in sec. \ref{integral}, then...
in TeX, this will provide proper section number references, and can be
used for pages, etc.
This is not currently implemented in Docutils/Sphinx. It would be easy to
achieve for LaTeX output, but in HTML this requires a transform that
extracts the section/table/theroem/... number and uses it as link text.
See the test
http://docutils.sourceforge.net/sandbox/latex-variants/tests/figure-reference.txt
for an example how this works with Docutils. (Not tested with the Sphinx
LaTeX writer.)
See also the Docutils TODO list
http://docutils.sourceforge.net/docs/dev/todo.html#object-numbering-and-object-references
- clean use of bibtex, including style file control.
Not implemented.
This is a long standing TODO list item.
http://docutils.sourceforge.net/docs/dev/todo.html#footnote-citation-gathering
There is some support with the external bibstuff add-on
http://code.google.com/p/bibstuff/
and with `Zotero plain`
http://e6h.org/%7Eegh/hg/zotero-plain/
- figure placement hints for floating figures.
This should hopefully be possible by modifying the Tex code generation.
You can already configure the float placement with the help of the float
package - globally with e.g. ::
\usepackage{float}
\floatplacement{figure}{tb}
in the LaTeX preamble, locally with raw latex like::
.. raw:: latex
\floatplacement{figure}{tb}
See
http://docutils.sourceforge.net/docs/user/latex.html#figure-placement
...
However, it just occured to me, that almost all of the problems could
be fixed by simply merging all the .rst files into one by my own
script, and only then giving it to Sphinx.
Instead of merging the .rst files, you can simply ``.. include::`` them
into a master document. Then, you might also consider using Docutils
instead of Sphinx for the LaTeX generation.
Günter
--
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: equations references across files
Hey Fernando,
On Fri, Jan 6, 2012 at 3:22 PM, Fernando Perez fperez@gmail.com wrote:
Hey Ondrej,
2012/1/6 Ondřej Čertík ondrej.cer...@gmail.com:
I didn't manage to work on this yet. If somebody who knows sphinx
internals can provide a hint how to best fix this, that'd be awesome.
are the other parts of writing a thesis/book with sphinx working OK
for you? I'm thinking:
- labeled references for other elements besides equations, such as saying
as we discuss in sec. \ref{integral}, then...
in TeX, this will provide proper section number references, and can be
used for pages, etc. I haven't actually tried this with sphinx, so
maybe it already works with standard ref_ type labels.
That seems to work well across pages. See for example here:
http://theoretical-physics.net/dev/src/quantum/hf.html#nonlocal-exchange-potential-in-spherical-symmetry
In html, it reproduces the section title,
and in Tex it produces this code:
We used the result of the integral in
{\hyperref[src/math/spherical-harmonics:five-spherical-harmonics]{\emph{Example
VI}}} and also:
So this is not optimal for a thesis.
- clean use of bibtex, including style file control.
Not implemented.
- figure placement hints for floating figures.
This should hopefully be possible by modifying the Tex code generation.
- more robust use of your $$ extension. Have you updated it? I don't
remember the details, but I recall it was a bit fragile to use...
I didn't. It works great for me. I wrote already at least 300 pages of
math heavy book here:
http://theoretical-physics.net/
you can get there html version as well as a pdf. And it works 100% for me,
so I am not worried about that for writing a thesis.
There may be more I can't think of now.
In general, the sphinx latex style is not optimal, but I have managed
to hack it pretty well.
So I think that is doable. I think the only problem is with:
* equations and section references
* literature (bibtex), especially accross files
However, it just occured to me, that almost all of the problems could
be fixed by simply merging all the .rst files into one by my own
script, and only then giving it to Sphinx. Then the only problem to
fix is:
* bibtex
* modify the latex template so that the thesis conforms to the school
format requirements.
I think that's what I'll do.
Ondrej
--
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: equations references across files
2012/1/7 Ondřej Čertík ondrej.cer...@gmail.com: So I think that is doable. I think the only problem is with: * equations and section references * literature (bibtex), especially accross files However, it just occured to me, that almost all of the problems could be fixed by simply merging all the .rst files into one by my own script, and only then giving it to Sphinx. Then the only problem to fix is: * bibtex * modify the latex template so that the thesis conforms to the school format requirements. I think that's what I'll do. True, and it may be the right solution for you. Though it would be great if instead of needing manual post-processing with extra tools, this was possible out of the box in sphinx. It's trivial to export an ipython notebook to rst, so if these things were possible within sphinx, the combination of sphinx and ipython would make it very, very easy to create complex documents like your book or a thesis but with sections that have code and plots produced from notebooks. All you'd need is in your makefile to have a rule %.rst : %.ipynb ipython nbexport --sphinx $ [ note, right now 'ipython nbexport' doesn't really exist, but the basics are just this: https://gist.github.com/1569580 and we'll have it soon in a more clean implementation] Your sphinx project could then consist of a mixture of hand-written .rst files and ipynb ones for the compute-heavy stuff. Obviously one could carry around your script as an extra tool, but the more this works out of the box, the easier gaining widespread adoption it will be. Still, do let us know how it goes and please do post any additional tools you develop for this; we're likely to reuse them :) 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-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: equations references across files
On Thu, Jan 5, 2012 at 1:12 AM, Woltan Schume w.sch...@googlemail.com wrote: I just ran into the same problem. Is there an update to this? I didn't manage to work on this yet. If somebody who knows sphinx internals can provide a hint how to best fix this, that'd be awesome. Ondrej -- 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: equations references across files
Hey Ondrej,
2012/1/6 Ondřej Čertík ondrej.cer...@gmail.com:
I didn't manage to work on this yet. If somebody who knows sphinx
internals can provide a hint how to best fix this, that'd be awesome.
are the other parts of writing a thesis/book with sphinx working OK
for you? I'm thinking:
- labeled references for other elements besides equations, such as saying
as we discuss in sec. \ref{integral}, then...
in TeX, this will provide proper section number references, and can be
used for pages, etc. I haven't actually tried this with sphinx, so
maybe it already works with standard ref_ type labels.
- clean use of bibtex, including style file control.
- figure placement hints for floating figures.
- more robust use of your $$ extension. Have you updated it? I don't
remember the details, but I recall it was a bit fragile to use...
There may be more I can't think of now.
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-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.
[sphinx-dev] Re: equations references across files
I just ran into the same problem. Is there an update to this? Cherio Woltan -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To view this discussion on the web visit https://groups.google.com/d/msg/sphinx-dev/-/X6QQtFVze18J. 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.
