I'm building my python package documentation as HTML and as a latex PDF. The default latex pdf generated (manual class) has a large amount of white space at the top of the table of contents around the text "CONTENTS". I'm not super familiar with latex so when I've look at the generated .tex file I don't see anything that tells me how to remove the whitespace.
I've searched around and couldn't find a latex solution that worked. I also tried setting the :caption: on the toctree to an empty string, but that actually removes the entire TOC and all of my content.
Can anyone help me with this?
The default behaviour of Sphinx for English language is to use Bjarne option to LaTeX package fncychap for chapter headings. But it also loads package titlesec for generally speaking title headings. It does not make a special chapter definition with titlesec, which simply gather the fncychap definition and wraps it in its own hooks. Anyway, making the story short we find
\ttl#save#mkschap #1->\vspace *{50\p# }{\parindent \z# \raggedright \normalfont \interlinepenalty \#M \DOTIS {#1} \vskip 40\p# }
in a log trace and this is the fncychap definition of \#makeschapterhead as preserved by titlesec in its own macro \ttl#save#mkschap.
fncychap is loaded before sphinx.sty, there is no hook,
edit: in fact the 'fncychap' key whose default value is '\\usepackage[Bjarne]{fncychap}' could serve to add some code to redefine the fncychap setting for un-numbered chapter titles. It is not that different from the approach with 'preamble' key below, except that one would not have needed knowing about titlesec intervention in all this.
but since recent Sphinx 1.5 you can use your own Jinja template for latex content. From the look of your contents which is small, I think you have an older version of Sphinx thus I will go for the LaTeX hacking variant something like this:
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
'preamble': r"""
\makeatletter
\def\ttl#save#mkschap #1{\vspace *{10\p# }{\parindent \z# \raggedright
\color{blue}%
\normalfont \interlinepenalty \#M \DOTIS {#1} \vskip 10\p# }}
\makeatother
""",
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
I have added a \color{blue} in there for demonstration purposes only, and modified the \vspace and \vskip commands which is what you need.
The image shows however that there is some extra source of vertical space between Contents and the TOC contents (it remains even with \vskip 0\p# but one can do \vskip -40\p# ...), but I think you are after the top space above Contents and already using only \vspace*{10pt} reduced it a lot (not visible in screenshot below).
Related
Having trouble setting text font style as Times New Roman for this document. I want all the test to be times new roman size 10. I generated a font table that holds the type and its the only type of my document. I want all the text to be times new roman but whenever the doc is generated it says its corrupted for some reason but if I don't set the font style the doc comes out in courier text as default and its not corrupted.
{\fonttbl{\f1\froman\fprq0\fcharset0 Times New Roman;}
\par
Hi <#name#>
\par\par
Welcome to New York \par\par
\b New iPad\'ae App Is Available \b0 \par
These are all the exciting things you cna do during your stay. \par \par
}
You're missing a lot of formatting in your example up there. For example, save a very simple RTF file from Wordpad or another application (Word puts in too much metadata) and see everything that you're missing.
First, Here is the most recent RTF Spec, 1.9.1. This will help you work through anything RTF related.
Second, any RTF document must start with \rtf*N* where N is the RTF Version (currently 1). You're missing this in your example. This is among one of the many reason why it is saying the file is corrupted.
Third, you define something in the font table and then don't use the definition, f1. This is an old spec for RTF, 1.6, but look at how the font table is defined.
There are many other things, but I think that you're using RTF like you would use HTML or something with tags. I would readup on the specification to see how RTF works. Here is a very small RTF document:
{\rtf1\ansi\ansicpg1252\uc1\htmautsp\deff2
{\fonttbl{\f0\fcharset0 Times New Roman;}{\f2\fcharset0 Tahoma;}}
{\colortbl\red0\green0\blue0;\red255\green255\blue255;}
\loch\hich\dbch\pard\plain\ltrpar\itap0{\lang1033\fs16\f2\cf0 \cf0\ql
{\f2 {\ltrch This is a test of RTF.}\li0\ri0\sa0\sb0\fi0\ql\par}}}
I am trying find particular tag in an xbrl file. I originally tried using python-xbrl package, but it is not exactly what I want, so I based my code on the one available from the package.
Here's the part of xbrl that I am interested in
<us-gaap:LiabilitiesCurrent contextRef="eol_PE2035----1510-Q0008_STD_0_20150627_0" unitRef="iso4217_USD" decimals="-6" id="id_5025426_6FEF05CB-B19C-4D84-AAF1-79B431731049_1_24">65285000000</us-gaap:LiabilitiesCurrent>
<us-gaap:Liabilities contextRef="eol_PE2035----1510-Q0008_STD_0_20150627_0" unitRef="iso4217_USD" decimals="-6" id="id_5025426_6FEF05CB-B19C-4D84-AAF1-79B431731049_1_28">147474000000</us-gaap:Liabilities>
Here is the code
python-xbrl package is based on beautifulsoup4 and several other packages.
liabilities = xbrl.find_all(name=re.compile("(us-gaap:Liabilities)",
re.IGNORECASE | re.MULTILINE))
I get the value for us-gaap:LiabilitiesCurrent, but I want value for us-gaap:Liabilities.
Right now as soon as it finds a match it, stores it. But in many cases its the wrong match due to the tag format in xbrl. I believe I need to change re.compile() part to make it work correctly.
I'd be very wary about using this approach to parsing XBRL (or indeed, any XML with namespaces in it). "us-gaap:Liabilities" is a QName, consisting of a prefix ("us-gaap") and a local name ("Liabilities"). The prefix is just a shorthand for a full namespace URI such as "http://fasb.org/us-gaap/2015-01-31", which is defined by a namespace declaration, usually at the top of the document. If you look at the top of the document you'll see something like:
xmlns:us-gaap="http://fasb.org/us-gaap/2015-01-31"
This means that within the scope of this document, "us-gaap" is taken to mean that full namespace URI.
XML creators are free to use whatever prefixes they want, so there is no guarantee that the element will actually be called "us-gaap:Liabilities" across all documents that you encounter.
beautifulsoup4 has very limited support for namespaces, so I wouldn't recommend it as a starting point for building an XBRL processor. It may be worth taking a look at the Arelle project, which is a full XBRL processor, and will make it easier to do other tasks such as finding the labels and other information associated with facts in the taxonomy.
Try it with a $ dollar sign at the end to indicate not to match anything else following the dollar sign:
liabilities = xbrl.find_all(name=re.compile("(us-gaap:Liabilities$)",
re.IGNORECASE | re.MULTILINE))
I started working with doxygen to generate the documentation of my Python code.
I use doxypy filter to preprocess the Python docstrings.
My goal is to have a nice syntax highlighting of doxygen comments in Python.
When writing my mainpage in a dedicated .dox file, I found that the doxygen comments can be highlighted in vim with the following command:
set syntax=c.doxygen
I tried the same command for Python but I got nothing:
set syntax=python.doxygen
I also made some googling and couldn't find anything interesting
Here is a typical piece of code I'd like to highlight:
class CompilationTab:
"""
The compilation tab of the verif GUI. It contains the layout description
and the functions required to deal with specific behaviors of the tab
"""
def __init__(self, notebook, tab_name):
"""
The class constructor.
#param notebook Notebook: The parent #c Notebook widget
#param tab_name String: The display name of the tab
"""
Does anybody already fixed this issue?
Thank you for help!
If you look into syntax/doxygen.vim you can read in the preamble of the file that currently only
cpp, c, idl, doxygen and php
files are supported.
Since doxygen.vim works a lot with the syn region command i searched for the line that defines the multiline string in syntax/python.vim.
The interesting part of the command that defines this region is
syn region pythonString start=+[uU]\=\z('''\|"""\)+ end="\z1" keepend
Derived from that what is in doxygen.vim and the above line you can add the following lines
"delete the following line if you don't want to have enhanced colors
let g:doxygen_enhanced_color=1
runtime! syntax/doxygen.vim
syn region doxygenComment matchgroup=pythonString start=+[uU]\=\z('''\|"""\)+ end="\z1" contains=doxygenSyncStart,doxygenStart,doxygenTODO keepend fold containedin=pythonString
to ~/.vim/after/syntax/python.vim or execute them by hand.
In addition you may have to customize the colors of the added doxygen highlighting groups by hand. At least i would do so since the resulting look doesn't conform with my taste.
Perhaps the fold argument of the syn command is of special interest for you. If you set foldmethod to syntax you can fold and unfold the multiline comments. That seems to be useful if you could no longer stand the view of those colors and are to lazy to adjust them :)
without doxygen highlighting:
with doxygen highlighting and g:doxygen_enhanced_color == 1:
I'm trying to get numbered figures to work on my Sphinx documentation project using latexpdf output. I installed the Sphinx numfig.py extension found here https://bitbucket.org/arjones6/sphinx-numfig
However, whenever I use the :num: tag that is supposed to provide a cross reference with the figure's number I instead get the following
rst
.. _fig_logo:
.. figure:: logo.*
Example of a figure
Reference to logo :num:`figure #fig_logo`
Generates output:
Reference to logo figure ??
Am I doing something wrong?
Seems that if you have an underscore in your label name (like in fig_logo) sphinx replaces this with a minus (-, this makes sense as latex sometimes behaves strange in cases whit underscores), while the reference still uses the underscore.
For that reason latex can not find the label referenced.
This is the resulting tex code generated by sphinx:
\includegraphics{logo.png}
\caption{Example of a figure}\label{index:fig-logo}\end{figure}
Reference to logo \hyperref[index:fig_logo]{figure \ref*{index:fig_logo}}
(Note the difference between fig-logo as label and fig_logo as reference.)
If you replace the underscore by a minus for instance
.. _fig-logo:
.. figure:: logo.png
Example of a figure
Reference to logo :num:`figure #fig-logo`
the tex code looks like this:
\includegraphics{pandas_bar.png}
\caption{Example of a figure}\label{index:fig-logo}\end{figure}
Reference to logo \hyperref[index:fig-logo]{figure \ref*{index:fig-logo}}
and in the pdf generated this is resolved to
Reference to logo figure 1
Update
If you don't want to change all the labels you can update numfig: it should be sufficient to add the line
target = target.replace('_', '-')
just before line 27 in your copy of the extension.
I opened an issue on bitbucket.
I recently discovered the genshi.builder module. It reminds me of Divmod Nevow's Stan module. How would one use genshi.builder.tag to build an HTML document with a particular doctype? Or is this even a good thing to do? If not, what is the right way?
It's not possible to build an entire page using just genshi.builder.tag -- you would need to perform some surgery on the resulting stream to insert the doctype. Besides, the resulting code would look horrific. The recommended way to use Genshi is to use a separate template file, generate a stream from it, and then render that stream to the output type you want.
genshi.builder.tag is mostly useful for when you need to generate simple markup from within Python, such as when you're building a form or doing some sort of logic-heavy modification of the output.
See documentation for:
Creating and using templates
The XML-based template language
genshi.builder API docs
If you really want to generate a full document using only builder.tag, this (completely untested) code could be a good starting point:
from itertools import chain
from genshi.core import DOCTYPE, Stream
from genshi.output import DocType
from genshi.builder import tag as t
# Build the page using `genshi.builder.tag`
page = t.html (t.head (t.title ("Hello world!")), t.body (t.div ("Body text")))
# Convert the page element into a stream
stream = page.generate ()
# Chain the page stream with a stream containing only an HTML4 doctype declaration
stream = Stream (chain ([(DOCTYPE, DocType.get ('html4'), None)], stream))
# Convert the stream to text using the "html" renderer (could also be xml, xhtml, text, etc)
text = stream.render ('html')
The resulting page will have no whitespace in it -- it'll look normal, but you'll have a hard time reading the source code because it will be entirely on one line. Implementing appropriate filters to add whitespace is left as an exercise to the reader.
Genshi.builder is for "programmatically generating markup streams"[1]. I believe the purpose of it is as a backend for the templating language. You're probably looking for the templating language for generating a whole page.
You can, however do the following:
>>> import genshi.output
>>> genshi.output.DocType('html')
('html', '-//W3C//DTD HTML 4.01//EN', 'http://www.w3.org/TR/html4/strict.dtd')
See other Doctypes here: http://genshi.edgewall.org/wiki/ApiDocs/genshi.output#genshi.output:DocType
[1] genshi.builder.__doc__