sphinx-doc / sphinx Goto Github PK
View Code? Open in Web Editor NEWThe Sphinx documentation generator
Home Page: https://www.sphinx-doc.org/
License: Other
The Sphinx documentation generator
Home Page: https://www.sphinx-doc.org/
License: Other
Make autodoc directives easily extendable, as proposed in
[comment from OP]
I'd like to retract my proposition, or rather rephrase it.
Extending autodoc would be simpler if directives such as function, class, method were
defined as classes rather than in the desc_directive function.
Something like:
class Description(Directive):
def __init__
def handle_options
def handle_signature
def handle_content
def handle_field_list
def index_as
def run
Extending autodoc would then simply be a matter of subclassing those directive. I
used this approach to write directives to autodocument fortran code (fortrandoc on
launchpad) and I found it worked well.
Reported by isopogon, Sep 17, 2008
The attached patch changes note_labels_from() to extract figure captions as
labels, so :ref: to a figure gets the correct label.
sphinx-figure-caption-patch
1022 bytes Download
Comment 1 by georg.brandl, Sep 17, 2008
Does every figure node contain a caption? If not, sectname may be undefined after the
elif block.
Labels: Type-Enhancement Milestone-0.5 Component-Markup
Comment 2 by isopogon, Sep 17, 2008
Ah. Whoops. I'll fix that and upload another patch.
Comment 3 by isopogon, Sep 17, 2008
Okay, this should work better.
sphinx-figure-caption-patch2
1.0 KB Download
Comment 4 by georg.brandl, Sep 24, 2008
Thanks! Committed in r66591.
When there is invalid latex in a math:: directive, and sphinx.ext.pngmath is in use, html build fails in the writing phase.
It would be more friendly to only output a warning in this case.
Here's a possible solution:
https://bitbucket.org/pv/sphinx-work/changeset/2b0cbcac9732/
I dislike the above approach a bit, but didn't know how to properly issue docutils errors in the writer phase.
Support reST-style citations in a consistent way across documents, so that
an automatic bibliography can be created for LaTeX documents.
Sphinx should support the suggested "seealso" protocol, see
http://svn.python.org/projects/sandbox/trunk/seealso/ and
http://effbot.org/zone/idea-seealso.htm.
Generated pages like //genindex// can be referenced with alternative name:
#!restructuredtext
Works:
See :ref:`genindex`
Does not work:
See :ref:`index listing <genindex>`
How to make a reference like?
See :ref:<genindex#A>`
I have an option list, formatted like:
"""
-h
Displays abbreviated help message.
--help
Displays complete usage information.
"""
The output in HTML and PDF from version 0.4.2 shows the "--" in front of "--help" converted to a single hyphen character.
[moved from http://bugs.python.org/issue2608]
I just created manpages for sphinx-build and sphinx-quickstart as a
part of Sphinx debianization.
Feel free to use/change/improve - I'm releasing them under BSD license,
matching rest of Sphinx.
Since the JS-based search is not optimal for every project.
Reported by isopogon, Sep 19, 2008
The redefinition of \includegraphics that is done by sphinx.sty is
preventing images being centered. The comment on the macro reads:
% Redefine includgraphics for avoiding images larger than the screen size
% If the size is not specified.
For my purposes, commenting out the macro appears harmless.
Comment 1 by isopogon, Sep 19, 2008
Ah - commenting out the macro isn't entirely harmless: the macro scales images wider
than the page to the page boundaries - so commenting it out means wide images spill
off the RHS of the page. I don't know enough LaTeX to fix this one.
Since headings are usually better matches.
I'm trying to modify the latex writer in an attempt to render the
footnotes inline, rather than at the end of the section, which doesn't
make a lot of sense in a page-oriented medium like PDF.
What I've done is to make the start_of_file node contain the
per-source-file nodes, rather than being a sibling of them. This allows
the writer to track per-source-file state (such as the list of footnotes):
on visiting start_of_file, I call traverse to collect up references to
all the footnote definitions, then when I encounter a footnote_reference,
I'll call the walkabout method on the previously collected footnote.
I've done some quick tests, and the approach results in no obvious
problems - I just wondered if you forsee any problems with what I'm doing?
In templates/search.html "less words" should be "fewer words".
Needs adapting the code from the existing docutils writer.
Allow direct PDF generation via rst2pdf http://rst2pdf.googlecode.com and reportlab.
There are apparently problems with classmethods in autodoc, a patch is at
http://groups.google.com/group/sphinx-dev/web/sphinx-method-fixes.diff
== Steps to reproduce: ==
Create project with sphinx-quickstart.exe name it Test.
Run sphinx-build -b htmlhelp source build
Build will be succsessful.
Now open conf.py and rename project variable to u'Тест' this is Test on
Ukrainian and Russian.
Try to build, you'l recieve exception at htmlhelp.py in build_hhx function:
#!python
UnicodeEncodeError: 'ascii' codec can't encode characters in position
317-323: ordinal not in range(128)
Code that throw exception:
f.write(project_template % {'outname': outname,
'title': builder.config.html_title,
'version': builder.config.version,
'project': builder.config.project})
In this case function tries to write utf8 data as ascii.
=== Sphinx version: ===
sphinx-0.5dev_20081115-py2.6.egg
=== OS ===
Windows Vista SP1
Test project in attachment.
There should be a way to document multiple programs and their options, like
suggested in
http://groups.google.com/group/sphinx-dev/browse_thread/thread/2b352fedee99fe70/b77acad064aae51b?lnk=gst&q=cmdoption#b77acad064aae51b.
[moved from http://bugs.python.org/issue4189]
When Sphinx builds TOC nodes, it isn't applying the tilde rule (use only
the last dotted name). For example compare the heading for:
to the table of contents at the top of the page, or to the node's link on:
http://people.osafoundation.org/~jeffrey/rearch_documentation/Chandler-Platform/README.html
I got the attached error when my source document exceeded the number of heading levels that the latex builder could handle. Yes, I should restructure my document :-) but a better error message would have been helpful in figuring out the problem.
Reported by p...iki.fi, Oct 19, 2008
r66916 in Sphinx SVN apparently broke Latex builds: the following
error occurs:
$ make all-pdf
...
(/usr/share/texmf-texlive/tex/plain/misc/pdfcolor.tex)
! Extra \fi.
l.62 \fi\fi
?
! Emergency stop.
l.62 \fi\fi
! ==> Fatal error occurred, no output PDF file produced!
The offending line is line 62 in sphinx.sty, this part:
57 % XeLaTeX can do colors, too
58 \IfFileExists{ifxetex.sty}{\RequirePackage{ifxetex}}{}
59 \ifx\ifxetex\undefined\else\ifxetex
60 \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
61 \def\py@TitleColor{\color{TitleColor}}
62 \fi\fi
Removing the second \fi on line 62 fixed the problem for me.
I'm using Texlive (2007, as shipped with Ubuntu intrepid).
Comment 1 by georg.brandl, Oct 19, 2008
This should already have been fixed in r66968.
Comment 2 by p...iki.fi, Oct 21, 2008
I see this with r66969. (Sorry, forgot to mention this.)
Bisection search shows that the first revision that fails for me is r66916.
However, installing the texlive-xetex package on Ubuntu (Intrepid) fixes this issue.
This package contains eg. ifxetex.sty
Adding a width option to an image directive breaks latex on my system (Ubuntu 8.04). These lines:
.. image:: ../flydra/autogenerated/plot_kalman_2d.png
:width: 600
Cause the following output when "make all-pdf" is run.
<plot_kalman_2d.png, id=177, 578.16pt x 433.62pt>
! Illegal unit of measure (pt inserted).
<to be read again>
\relax
l.427 ...degraphics[width=600]{plot_kalman_2d.png}
?
When the width option is removed, that PDF builds fine.
Thanks,
Andrew
[moved from bugs.python.org issue 4056]
I used a reference like :Class:something
(note the capitalization) and
got this exception:
Traceback (most recent call last):
File
"/home/ianb/src/env/lib/python2.4/site-packages/sphinx/init.py",
line 135, in main
app.builder.build_update()
File
"/home/ianb/src/env/lib/python2.4/site-packages/sphinx/builder.py", line
201, in build_update
summary='targets for %d source files that are '
File
"/home/ianb/src/env/lib/python2.4/site-packages/sphinx/builder.py", line
241, in build
self.write(docnames, updated_docnames, method)
File
"/home/ianb/src/env/lib/python2.4/site-packages/sphinx/builder.py", line
276, in write
doctree = self.env.get_and_resolve_doctree(docname, self)
File
"/home/ianb/src/env/lib/python2.4/site-packages/sphinx/environment.py",
line 779, in get_and_resolve_doctree
self.resolve_references(doctree, docname, builder)
File
"/home/ianb/src/env/lib/python2.4/site-packages/sphinx/environment.py",
line 998, in resolve_references
raise RuntimeError('unknown xfileref node encountered: %s' % node)
RuntimeError: unknown xfileref node encountered: <pending_xref classname
modname refcaption="False" reftarget="deliverance.rules.Drop"
reftype="Class">deliverance.rules.Drop</pending_xref>
Reported by steve.milner, Sep 27, 2008
These patches move single lines with multiple imports into multiple lines.
For instance:
import os, sys
becomes
import os
import sys
Also did a bit of spacing between functions.
sphinx-imports-and-spacing-for-a-few-files.patch
4.3 KB Download
sphinx-tests-imports.patch
1.2 KB Download
Comment 1 by georg.brandl, Oct 16, 2008
I don't think these patches add anything of value.
[moved from http://bugs.python.org/issue4203]
Hello,
for users on the windows platform, it could be of great help if the
sphinx-quickstart would be adjuste to their platform.
Here are my suggestions:
Thanks for your great tool!
If I do this then the exception isn't linked (I have it defined via .. exception:: elsewhere)
:raises MyException:
Trying the workaround doesn't work either. The raises bit is malformatted although the MyException is now linked.
:raises :exc:MyException
:
Don't blindly copy all static files, but allow specifying which ones are
needed. This isn't very important right now, but can be problematic later
when more themes etc. are added.
There should be an option to generate the module index compactly, not
showing the synopses for every module.
[Comment 1 by ted.drain, Sep 14, 2008]
Assuming I understand the intent of this, it would be nice to extend this to also
support generating a short class index as well. Something similar to what
doxygen/javadoc/others do is a page something something like:
I want another CSS file to be included after the normal Sphinx ones but can't see any way to do that.
For example lets say I wanted to add background for "highlight-python".
Currently it looks like I have to copy the entire default.css and then add my one line at the end which means I have to track default.css as it changes in the future.
When rendering to LaTeX, tables can spill off the bottom of the page if
they contain enough rows. The old Python docs used \longtable in these
situations, which supports splitting over pages.
My first thought was to make the latex writer emit \longtable if the table
had more than (say) 30 rows, but the logic does not make this easy. Another
option is to switch to using \longtable unconditionally, but the old python
docs cautioned against using it with tables of less than 20 rows.
Other suggestions gratefully received.
There should be an option to automatically number section headings in HTML output.
There should be an extension that includes a highlighted version of the
source code, with cross-references between it and the documentation.
See http://article.gmane.org/gmane.comp.python.sphinx.devel/922
In summary there more specific "highlight-foo" should be inside "highlight" and it can all be done using one div anyway.
An example usecase is if the background for "highlight" is one colour and for "highlight-python" is another. Python code should pick up the latter.
locale file for Chinese Traditional interface, tested on 11/12 hg clone.
sphinx/texinputs/Makefile contains a syntax error that causes the makeindex
runs to silently fail. The attached patch addresses this.
In docstrings, we often want to refer to other functions without
necessarily describing them. For this use case, it would be practical to
simply pass a list of references as arguments to the seealso directive.
eg.
.. seealso:: :func:foo
, :class:bar
I don't usually have javascript enabled in my browser (firefox+ the noscript extension).
The search box in the sidebar doesn't work without javascript. It should probably be disabled (hidden) if the browser doesn't have scripting support.
The search page should provide some kind of feedback when javascript isn't enabled too.
With some guidance I could probably help resolving this.
thanks.
Reported by trentm, Oct 08, 2008
What steps will reproduce the problem?
Build the Python docs' "htmlhelp" target:
cd python/Doc
make htmlhelp
What is the expected output? What do you get instead?
The created .hhc (Table of Contents file for HTML Help) has unescaped
double-quotes in node "value" attributes. For example you'll see something
like this:
That makes the .hhc file invalid XML. While I believe the MS Help compiler
(hhc.exe) is fine with that -- it makes it a pain to do any post-processing
on the .hhc file. :)
Attached is a proposed patch to fix this that transforms double-quotes to
'"'.
Here is the bug for this on ActivePython:
http://bugs.activestate.com/show_bug.cgi?id=80298
If I run the linkchecker then I get a list of all links as they are checked which is several screenfuls with my doc. If I use -q then there is no output at all, not even any errors. The errors are in the output.txt but I'd prefer them to be shown when running sphinx-build. Also sphinx-build exits with 0 (success) even though links are broken.
This is what I see:
sphinx-build -q -b linkcheck -d build/doctrees . build/linkcheck
Link check complete; look for any errors in the above output or in build/linkcheck/output.txt.
This is what is in output.txt:
download.rst:13: [broken] http://apsw.googlecode.com/files/apsw-3.6.5-r1.zip: HTTP Error 404: Not Found
download.rst:17: [broken] http://apsw.googlecode.com/files/apsw-3.6.5-r1.win32-py2.3.exe: HTTP Error 404: Not Found
download.rst:21: [broken] http://apsw.googlecode.com/files/apsw-3.6.5-r1.win32-py2.4.exe: HTTP Error 404: Not Found
download.rst:25: [broken] http://apsw.googlecode.com/files/apsw-3.6.5-r1.win32-py2.5.exe: HTTP Error 404: Not Found
download.rst:29: [broken] http://apsw.googlecode.com/files/apsw-3.6.5-r1.win32-py2.6.exe: HTTP Error 404: Not Found
download.rst:35: [redirected] http://packages.debian.org/python-apsw to http://packages.debian.org/search?keywords=python-apsw
exceptions.rst:196: [redirected] http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52215 to http://code.activestate.com/recipes/52215/
index.rst:9: [redirected] http://www.pysqlite.org to http://oss.itsystementwicklung.de/trac/pysqlite/
vtable.rst:23: [broken] http://www.josephson.org/projects/pyamazon:
This is happening with current tip. If you example the HTML head section of modindex.html then there is a line like this:
<generator object at 0x3290e60>
It is after the link rel="top" and before the javascript. You can see an example at http://code.google.com/p/apsw/source/browse/publish/modindex.html
Add "download" role and automatically copy so-referenced files to a special
download folder in built docs.
This issue contains two bugs in htmlhelp index.
See http://bugs.python.org/issue4252.
In index_on_firefox.png, we can see "operator, [1], [2]". This [?] means multiple targets are linked to same keyword and we can browse each target in firefox. But from htmlhelp, we can only browse first target.
Attached patch will enable us to select each targets in popup dialog. (They all have same title, I think it's useless though)
[moved from http://bugs.python.org/issue3655]
LaTeXTranslator.visit_footnote_reference generates improper Latex if
the footnote marker given is not a number. This will result in a Latex
error if the RST document contains footnotes where the marker is not a
number.
The problem is that the Latex commands \footnotemark and \footnotetext
apparently expect their [] argument to always be a number.
For example:
\footnotemark[x]
results to error:
! Missing number, treated as zero.
<to be read again>
x
l.4733 ...\footnotemark[x]
literalinclude should get options for including only sections (marked up by
specially formatted comments) or objects (as returned by inspect.getsource).
The generated TOCs currently have redundant
The effect of vertical space between content from different levels should
be done via CSS.
Consider adding a "guess" pseudo-language to the PygmentsBridge as a
transitional aid for people converting large documents with mixed code
literals.
Implement autoattribute directive via module parsing and extraction of
documentation comments like
#: maximum number of parrots
NUM_PARROTS = 5
Add some directive that automatically generates an RSS feed for its items.
While experimenting with the improved autodoc in hg I noticed it ignores module-level functions when asked to document a c extension module. This is simply because the check at the bottom of RstGenerator.generate only lets through functions of type types.FunctionType, while functions implemented in c are of type types.BuiltinFunctionType. The attached trivial patch to accept that type as function too seems to work fine.
http://sphinx.pocoo.org/ has a link for "You can also open an issue at the tracker." that points at http://code.google.com/p/sphinx/issues/list which seems to be deprecated. This is not immediately obvious. This should probably be updated, assuming where I am posting this is indeed the new bug tracker :)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.