Re: [sphinx-dev] Programmatic use of sphinx
On Thu, Aug 12, 2010 at 8:03 AM, Mango wrote:
> Hello Sphinx devs!
>
> First of all thanks for the great tool! I'm from the OpenAlea (python)
> project (http://openalea.gforge.inria.fr/wiki/doku.php?id=openalea)
> and we have started to move our documentation to sphinx.
>
> However, we want to push a little further than simply generating html
> files, we want to use sphinx to dynamically generate beautiful HTML
> from docstrings and display it in our application. OpenAlea gathers
> many components and this could be handy as third party components
> almost always ship with docstrings but not with html files.
>
> We started digging into the code and had some success with different
> methods, but nothing fully functionnal. First we simply used docutils
> but it couldn't parse sophisticated directives, then we built a
> solution around Sphinx (a small wrapper around class Sphinx and class
> StandaloneHTMLBuilder). It worked better but still, docutils
> complained about unknown roles ("func") that are defined in Domains
> and I finally gave up because I failed to properly wrap my head around
> Sphinx' code.
>
> I'd really appreciate if someone could explain me how Domain-roles are
> declared to docutils? I have seen some monkey patching in some places
> but couldn't get the right result. In the end what I would like to
> write is an API like this:
>
> builder.build_rst( rst_string, builder, writer, working_directory)
>
> .. so I could simply do:
> sphinxApp = sphinx.application.Sphinx(...)
> sphinxApp.builder.build_rst(" .. todo :\n\ntest",
>
> sphinx.builders.html.StandaloneHTMLBuilder,
>
> sphinx.writers.html.HTMLWriter,
> )
>
Have you looked at the JSONHTMLBuilder?
Kevin Horn
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to sphinx-...@googlegroups.com.
To unsubscribe from this group, send email to
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
[sphinx-dev] Programmatic use of sphinx
Hello Sphinx devs!
First of all thanks for the great tool! I'm from the OpenAlea (python)
project (http://openalea.gforge.inria.fr/wiki/doku.php?id=openalea)
and we have started to move our documentation to sphinx.
However, we want to push a little further than simply generating html
files, we want to use sphinx to dynamically generate beautiful HTML
from docstrings and display it in our application. OpenAlea gathers
many components and this could be handy as third party components
almost always ship with docstrings but not with html files.
We started digging into the code and had some success with different
methods, but nothing fully functionnal. First we simply used docutils
but it couldn't parse sophisticated directives, then we built a
solution around Sphinx (a small wrapper around class Sphinx and class
StandaloneHTMLBuilder). It worked better but still, docutils
complained about unknown roles ("func") that are defined in Domains
and I finally gave up because I failed to properly wrap my head around
Sphinx' code.
I'd really appreciate if someone could explain me how Domain-roles are
declared to docutils? I have seen some monkey patching in some places
but couldn't get the right result. In the end what I would like to
write is an API like this:
builder.build_rst( rst_string, builder, writer, working_directory)
.. so I could simply do:
sphinxApp = sphinx.application.Sphinx(...)
sphinxApp.builder.build_rst(" .. todo :\n\ntest",
sphinx.builders.html.StandaloneHTMLBuilder,
sphinx.writers.html.HTMLWriter,
)
--
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] Dynamic file order
Hello all, I'm currently building a collection of scripts for my team to use when writing reports. The plan is that they will create a bunch of rst files and Sphinx will turn them into a shiny PDF, or similar. Each rst file will have a priority associated with it and I was wondering what would be the best way to ensure the final document is ordered by this field. I.e. High first, then medium, etc. I've written a custom directive (not as scary as I thought) which can be used to specify the file's priority. So far I think the following are my best options: 1. Have a pre-build script that greps the files, extracts the priorities and updates the index. (not ideal, as the directive won't be used) 2. Hijack the toctree processing to do something similar to 1. 3. Create a custom writer that will process the doctrees and write them in the correct order. Can anyone suggest a better solution, or whether I've no hope of achieving this? Thanks in advance, Felix -- 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] Programmatic use of sphinx
Hello Sphinx devs!
First of all thanks for the great tool! I'm from the OpenAlea (python)
project (http://openalea.gforge.inria.fr/wiki/doku.php?id=openalea)
and we have started to move our documentation to sphinx.
However, we want to push a little further than simply generating html
files, we want to use sphinx to dynamically generate beautiful HTML
from docstrings and display it in our application. OpenAlea gathers
many components and this could be handy as third party components
almost always ship with docstrings but not with html files.
We started digging into the code and had some success with different
methods, but nothing fully functionnal. First we simply used docutils
but it couldn't parse sophisticated directives, then we built a
solution around Sphinx (a small wrapper around class Sphinx and class
StandaloneHTMLBuilder). It worked better but still, docutils
complained about unknown roles ("func") that are defined in Domains
and I finally gave up because I failed to properly wrap my head around
Sphinx' code.
I'd really appreciate if someone could explain me how Domain-roles are
declared to docutils? I have seen some monkey patching in some places
but couldn't get the right result. In the end what I would like to
write is an API like this:
builder.build_rst( rst_string, builder, writer, working_directory)
.. so I could simply do:
sphinxApp = sphinx.application.Sphinx(...)
htmlStr = sphinxApp.builder.build_rst(" .. todo :\n\ntest",
sphinx.builders.html.StandaloneHTMLBuilder,
sphinx.writers.html.HTMLWriter,
"/absolute/
path/to/temp/on_the_fly/documentation/directory" #for images, etc...
)
Any help would be greatly appreciated!
Thanks for reading,
Daniel
PS: mods, sorry for the previous attempt at posting this message which
was sent unfinished
--
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: modifications to the toctree() template function
I had a thought (wow). In your original question, you wanted a sidebar toc that displayed a list for a sub-grouping of docs. Can you build each sub-group of docs separately, then just combine the files? You would need a 'master' grouping as well, to give you an overall toc/sitemap. So your dir structure might be like this: Root/ Doc1 \doc1.1 Doc2 \doc2.1 So you would build doc1, doc2 and root. Doc1 output would have the toc for all of the doc1 grouping. Doc2 the same. Root would have a toc pointing to doc1 and doc2 Copy all build files to same location. -Original Message- From: sphinx-dev@googlegroups.com [mailto:sphinx-...@googlegroups.com] On Behalf Of andreash Sent: 11 August 2010 23:25 To: sphinx-dev Subject: [sphinx-dev] Re: modifications to the toctree() template function you're right, basic theme uses globaltoc.html template. but the code in there just calls the toctree() template function. which I also do. my question goes beyond that. my system doesn't seem to know any localtoc() function. where can i see which functions are available in the template, and how to use them? thanks for your insight :) a -- 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: modifications to the toctree() template function
Sorry, the function isn't called localtoc, it's just 'toc'. Some of the templates produce html with a toc that is just for the current file. Look for localtoc.html. Also mentioned here: http://sphinx.pocoo.org/config.html?highlight=localtoc Like you, I'm finding using some of the functions frustrating. I'm sure that the apparent lack of info on some things is due to them not actually being part of Sphinx, but adapted from the likes of Jinja -Original Message- From: sphinx-dev@googlegroups.com [mailto:sphinx-...@googlegroups.com] On Behalf Of andreash Sent: 11 August 2010 23:25 To: sphinx-dev Subject: [sphinx-dev] Re: modifications to the toctree() template function you're right, basic theme uses globaltoc.html template. but the code in there just calls the toctree() template function. which I also do. my question goes beyond that. my system doesn't seem to know any localtoc() function. where can i see which functions are available in the template, and how to use them? thanks for your insight :) a. On 11 Aug., 15:40, "Alastair Dent" wrote: > I was a bit woolly in my description, and on checking, I'm wrong as well. > > AFAIK, the sidebar is 'built' by taking info from an html file specified for > your theme. For my setup, that's > C:\Python26\Lib\site-packages\Sphinx-1.0b2-py2.6.egg\sphinx\themes\basic\globaltoc.html > > Can you use the function localtoc instead? > > -Original Message- > From: sphinx-dev@googlegroups.com [mailto:sphinx-...@googlegroups.com] On > Behalf Of andreash > Sent: 11 August 2010 11:45 > To: sphinx-dev > Subject: [sphinx-dev] Re: modifications to the toctree() template function > > I don't understand what you mean. What's the difference between > 'compile time' and 'runtime'? > > The toctree() template function takes parameters, which means that it > is evaluated when the HTML files are built. So it should just be a > matter of extending the Sphinx function which the template toctree() > function calls. But which is that? And how would I start? > > On Aug 9, 11:14 am, "Alastair Dent" wrote: > > As I understand it, the toctree is built at compile time, not runtime. > > So normally it is built, then inserted into the html file. > > > So the sidebars are built, then inserted. So what you are asking for > > would be quite complicated. > > > I use a 'local' toctree in a similar manner to what you are asking, but > > it is only in the first/overview html file for each chunk. > > > -Original Message- > > From: sphinx-dev@googlegroups.com [mailto:sphinx-...@googlegroups.com] > > > On Behalf Of andreash > > Sent: 09 August 2010 09:57 > > To: sphinx-dev > > Subject: [sphinx-dev] modifications to the toctree() template function > > > Hi there, > > > I'm using Sphinx 1.0.1 to build some websites. While adapting the > > basic template to my needs, I stumbled upon the need to modify the > > toctree() template function to accomodate several things. > > > Most importantly, I'd like to have toctree() an option to start at the > > level of the current document, and not at the root level. What I mean > > is this: > > > root/ > > doc1/ > > doc2/ > > doc2.1/ > > doc2.2/ > > doc3/ > > > So I'd like to have the option to render a sidebar menu which only > > contains the 'heading' "doc2", and then the members doc2.1 and doc2.2. > > I was thinking about an option toctree(startatcurrent=True) to > > accomodate this ... > > > Also, how do I get the title of and the link to the parent of the > > current document (to accomodate the 'heading' as descibed above)? > > > I've been searching through the Sphinx code for quite some while, but > > couldn'r really figure out which functions/variables are available to > > the templates. What I did find out is that probably the code that I > > want is in environment.py. But how would I go to implement changes? > > > Any help is greatly appreciated! > > > Cheers, A. > > > -- > > 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 > > athttp://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 > athttp://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-de
