documentation - 1/1 Blog automation (4) documentation (8) example (2) latex (2) notebook (4) sphinx (10)
documentation - 1/1¶
Make a reference to a blog post¶
2016-06-11
Make a reference to the label label-to-this-blogpost
to reference this blog post. Look at the source of this page
to see how this id was specified.
Producing a version for Python 2.7 from Python 3¶
2015-04-17
I tried to make most of the unit tests run under Python 2.7. Most of the function deals with strings for the documentation and it is a real pain to think again about str, unicode, bytes. Some of the functions only works in Python 3 but the goal was more to see what needed to be done.
The first issue came from exception:
try:
something
except Exception as e:
raise Exception("other message") from e
This syntax is not available and to avoid losing it, I decided to have two separate versions of the same module. I created a function py3to2_convert_tree <pyquickhelper.pycode.py3to2.py3to2_convert_tree> which copies the source and deals with this case (it removes everything it can).
I also had an issue with code like isinstance(v, long) as the long type
does not exists. So I added the string int #long#
to be replaced by long by a function. The one
I use the most is str #unicode# replaced by unicode.
The second issue is the function open. I usually use the following trick:
if sys.version_info[0]==2:
from codecs import open
It does not solve everything (strings become unicode) and will melt
with strings because I do not use u"..." which I could implement in
the function
py3to2_convert_tree <pyquickhelper.pycode.py3to2.py3to2_convert_tree>.
Running out of courage, I disabled some unit tests because they were not passing due to the encoding issues. I had to add in some files but maybe I should have added that everywhere:
from __future__ import print_function
The following is added everywhere:
from __future__ import unicode_literals
Migration to IPython 3.1¶
2015-04-16
It took me some time to do the migration to IPython 3.1. The code which automatically generates the documentation had to be updated to follow the new format of the notebooks. I had to redo the configuration of ipython to have the graph inline... I hope ipython does not rename itself into jupyter. The design is better but the notebooks crash from time to time. I guess the code becomes better each time a migration happens. But it takes quite some time. However, the changes are not reversible. Ipython needs to be updated otherwise the automated generation of the documentation will not work. For Jenkins, just remind that the server needs your credentials othewise it does not easily find pandoc.
Conversion to latex is taking for ever¶
2015-04-16
The unit tests are now scheduled using Jenkins. When the documentation is generated for the first time after a fresh installation of the machine (latex, sphinx...), the compilation can take for ever. This is due to extra packages needed by latex. When the process is run from a command line, a windows shows up asking for approval before going on installing the missing latex packages. As this command line is showing up in the output, it is just needed to executed from a command line window to import the missing package. After this short break, the latex compilation runs fine on Jenkins.
Anaconda does not have the latest version of Sphinx¶
2015-04-16
As of today, when I type conda update sphinx,
The Anaconda distribution does not upgrade to 1.3
and I need it to get the extension
sphinx.ext.napoleon. So I need to type
pip install sphinx --upgrade instead.
Insert plot from bokeh in the documentation¶
2015-04-12
As graphs from matplotlib, graphs from bokeh can be inserted in the documentation with the extension bokeh.sphinxext.bokeh_plot.
I replicate here the example from the documentation:
.. bokeh-plot::
from bokeh.plotting import figure, output_file, show
output_file("example_bokeh.html")
x = [1, 2, 3, 4, 5]
y = [6, 7, 6, 4, 5]
p = figure(title="example_bokeh", plot_width=300, plot_height=300)
p.line(x, y, line_width=2)
p.circle(x, y, size=10, fill_color="white")
show(p)
See example with bokeh to se the result. Including this code in the blog post fails but it should be fixed some days.
Last detail, for some reasons I don’t know, the instruction
output_file must remain. I tried different version
with different title and file name but it did not work either.
You should look into bokeh’s documentation to get a better
sense of how it works as this macro is used to generate the
documentation of the module.
Sphinx fails because of some weird encoding¶
2015-04-07
I have been generating many times the documentation of this module and I can tell I went through many errors due to encoding, French accents may be sometimes painful to deal with. However, I now check every time that every file I produce has either no encoding, either is encoded with utf-8 and no BOM. After I checked that, I’m sure the error come from something else.
The issue I had with Sphinx is not necessarily a crash but also
a label which was not takein into account.
This label was written on the first line of the line.
I replaced that label by a comment (.. comment.).
The comment showed on the generated HTML page but it disappear
after I removed the BOM from the original RST file.
An example of a blog post included in the documentation¶
2015-04-04
This blog post is an example of a blogpost which can be added to the documentation. Unfortunately, it does not rely on an existing python blog generator as it was difficult to entirely change the existing framework and to keep track on references.
It is just a rst file which starts with a header like the following:
.. blogpost::
:title: An example of a blog post included in the documentation
:keywords: example, blogpost, documentation
:date: 2015-04-04
:categories: documentation, example
However, you can check some of the following to power your blog: What’s the best available static blog/website generator in Python or this page which gathers many framework to build a static website: StaticGen Top Open-Source Static Site Generators.
documentation - 1/1 2015-04 (8) 2015-05 (4) 2015-08 (2) 2015-10 (1) 2015-12 (3) 2016-01 (1) 2016-02 (3) 2016-04 (1) 2016-06 (1)