I'm documenting my Python classes using Sphinx, and sometimes I want to give my parameters quite long descriptions to explain something in details. Unfortunately, Sphinx generates ugly output for me which wastes a lot of space and breaks the whole page appearance:
It can be seen that Sphinx creates a table, then puts "Parameters" header to the left cell, and the actual list of parameters to the right cell. But there should be way to avoid creating this table completely. After playing with the page DOM tree I finally can show that I want to achieve:
Is there a built-in way to do this or I'd have to create a PR to Sphinx theme or Sphinx itself?
After posting an issue to Sphinx bug-tracker and having no response, I've decided to roll-out my own solution (better say, hack). To achieve the look I want, I have written a simple Sphinx extension which post-processes generated HTML code. It can be found on PyPI:
https://pypi.python.org/pypi/sphinxcontrib.divparams
https://pythonhosted.org/sphinxcontrib.divparams/
This doesn't seem to be the best way to solve the issue, but the behaviour I wanted to change is deeply hard-coded in docutils, not Sphinx.
Related
I'm using Sphinx to document a python project, and I'm trying to create a reusable tip to be used in several locations.
Typically, I'll use the following syntax in a python file:
"""
.. tip::
I want this tip to be used in several locations. Why?
- Save time
- Work less
"""
Now this works whether I put it at the beginning of the file, right under class definition or right under function definition.
I found Sphinx's manual for :ref:, which suggests to use a label:
.. _my_reusable_tip:
.. tip::
...
And then call this tip with :ref:`my_reusable_tip` anywhere I want.
The manual states that 'it works across files, when section headings are changed, and for all builders that support cross-references'
The thing is, it doesn't matter in which .py file in the project I write the label and tip definition, the :ref:`my_reusable_tip` just displays 'my_reusable_tip', and not the tip itself.
What I'm using to build the documentation is
sphinx-apidoc -f -F -o
make html
I'm pretty sure my logic is flawed in some way, but I can't figure out why.
I know that Sphinx searches the project for reStructuredText and renders it if it can, but I think I'm missing something here.
I tried to add this label in a seperate .py file enclosed in """, and in a separate .txt file without enclosed """.
I tried creating an .rst file with the label definition and rebuild the html documentation.
What am I missing here?
Python 3.4.3 BTW.
In sphinx, a :ref: is simply a more robust way of linking (or referencing) another part of the document. Thus, your use of :ref: will simply provide a hyperlink to the label.
It is not a way of substituting or expanding a block.
Inline substitutions are available using using |...|, however an inline substitution cannot be used to substitute a block as you seem to require.
RestructuredText is not a template language, and thus doesn't provide macro like facilities. In the event you need it, an alternative solution is to use a template library such as mako or jinja to deal with this kind of issue.
Just using reStructuredText directive
.. include:: ./my_reusable_tip.txt
in your rst files?
I've got a Django app that I'm working on, with a wiki (powered by django-wiki) sitting under the wiki/ folder.
The problem I'm having is that if I create links using Markdown, they all direct to the root /, whereas I want any links generated from the markdown to go into the same subdirectory (under /wiki). The documentation doesn't appear to be particularly forthcoming on this (mainly directing me to to the source code, which so far has revealed nothing).
The other avenue I'm looking into is how to direct Markdown itself to prefix all links with a specified path fragment. Is there a Markdown extension or trick that might be useful for accomplishing this?
Well, it looks like there is just such an extension for this in MarkDown (WikiLinkExtension - which takes a base_url parameter).
I've had to modify my copy of django-wiki to add a new setting to use it (submitted an upstream pull request for it too, since I suspect this will be useful to others). Kinda surprised django-wiki didn't have this support already built but there you go.
EDIT: Ok, it looks like this approach doesn't play nice with a hierarchical Wiki layout (which Django-wiki is designed for). I've cobbled together a hack that allows me to link to child pages of the current page, which is enough to be workable even if it's kind of limited.
I'm writing a simple webpage generator based on restructuredtext and I'd like to put tags into the document, like this.
=====
Title
=====
:author: Me
:tags: foo, bar
Here we go ...
What I want now:
get in possession of some kind of document tree
find the tags entry, read it, process it (like print the tags on the command line), remove it and render the remaining tree.
So I'd like to write compatible restructuredtext in case it's being compiled with something different than my program.
Can someone give me a hint? I found this one here http://svn.python.org/projects/external/docutils-0.6/docutils/examples.py showing in the internals method how to obtain the document (and therefore the dom tree), but is this the best way to go or would a regex based approach (find lines, remove them) be a lot easier? Working with the tree would also involve the conversion tree → document and so on.
There are tools that can do this for you. See http://docutils.sourceforge.net/docs/user/links.html
I think I have a nice solution for both problems. First, the core.py file in the docutils distribution shows how to obtain the doctree and how to write it (using a html writer for instance), see publish_from_doctree and publish_doctree. Then, there is docutils.nodes.SparseNodeVisitor which one can subclass and overwrite methods like visit_field to manipulate the document tree in various ways.
see: http://diveintopython.net/native_data_types/lists.html#d0e5623
I have a website with code examples on it, generated through docutils, and the CSS is always not quite right.
I would like to know if there is
best practise CSS for displaying code (ie can it handle wrap arounds, long lines, any chance of getting colourisation)
best practise for the little numerical callouts (see diveintopython above)
and finally, I am wondering if there is (open) CSS that is designed to work with docutils HTML output and actually look "nice". I would be happy to contribute some CSS that makes tables look "microsoft professional grey" and so forth.
You can't do syntax highlighting with CSS alone. You need the various parts of the code to be marked up; you can do that on the server if you are using dynamic pages, or you can use JavaScript on the client. Here is a comparison of a few JavaScript syntax highlighters.
The circled numbers are images in the site you linked, but I would use Unicode instead: ❶➋➌➍➎➏➐➑➒➓
I have two chunks of text that I would like to compare and see which words/lines have been added/removed/modified in Python (similar to a Wiki's Diff Output).
I have tried difflib.HtmlDiff but it's output is less than pretty.
Is there a way in Python (or external library) that would generate clean looking HTML of the diff of two sets of text chunks? (not just line level, but also word/character modifications within a line)
There's diff_prettyHtml() in the diff-match-patch library from Google.
Generally, if you want some HTML to render in a prettier way, you do it by adding CSS.
For instance, if you generate the HTML like this:
import difflib
import sys
fromfile = "xxx"
tofile = "zzz"
fromlines = open(fromfile, 'U').readlines()
tolines = open(tofile, 'U').readlines()
diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile,tofile)
sys.stdout.writelines(diff)
then you get green backgrounds on added lines, yellow on changed lines and red on deleted. If I were doing this I would take take the generated HTML, extract the body, and prefix it with my own handwritten block of HTML with lots of CSS to make it look good. I'd also probably strip out the legend table and move it to the top or put it in a div so that CSS can do that.
Actually, I would give serious consideration to just fixing up the difflib module (which is written in python) to generate better HTML and contribute it back to the project. If you have a CSS expert to help you or are one yourself, please consider doing this.
I recently posted a python script that does just this: diff2HtmlCompare (follow the link for a screenshot). Under the hood it wraps difflib and uses pygments for syntax highlighting.
not just line level, but also word/character modifications within a line
xmldiff seems to be a nice package for this purpose especially when you have XML/HTML to compare. Read more in their documentation.
try first of all clean up both of HTML by lxml.html, and the check the difference by difflib
Since the .. library from google seams to have no active development any more, I suggest to use diff_py
From the github page:
The simple diff tool which is written by Python. The diff result can be printed in console or to html file.
A copy of my own answer from here.
What about DaisyDiff (Java and PHP vesions available).
Following features are really nice:
Works with badly formed HTML that can be found "in the wild".
The diffing is more specialized in HTML than XML tree differs. Changing part of a text node will not cause the entire node to be changed.
In addition to the default visual diff, HTML source can be diffed coherently.
Provides easy to understand descriptions of the changes.
The default GUI allows easy browsing of the modifications through keyboard shortcuts and links.