The purpose of this page is to exemplify how to write scientific reports in various formats: LaTeX PDF, HTML, Sphinx, IPython notebook, HTML blog post, etc.
The classical LaTeX-style report format is widely used throughout mathematical sciences. This PDF version was made from the hand-written DocOnce source report.do.txt, first translated to LaTeX source code and then compiled to PDF.
The necessary steps in this process go as follows.
# Compile DocOnce to LaTeX format
doconce format pdflatex report --latex_code_style=vrb
# Compile LaTeX to PDF
rm -f *.aux
pdflatex report
bibtex report
pdflatex report
DocOnce generates BibTeX from a bibliography file in the Publish format, as explained in the section Handling of literature citations.
Here is another version of the same report, this time in a fresher, more modern PDF format for electronic view where URLs and references are hyperlinks. This PDF file is made from LaTeX source generated from DocOnce source.
The steps to produce the PDF file are listed below. First, LaTeX code must be generated by
doconce format pdflatex report --latex_font=palatino \
--latex_admon=yellowicon '--latex_admon_color=yellow!5'
--latex_fancy_header --latex_code_style=pyg
--latex_section_headings=blue --latex_colored_table_rows=blue
The doconce format program has a lot of options
(see doconce format --help). Here we
fine-tune the way admonitions are typeset (admonitions are boxes for
warnings, tips, notes, questions, summaries, etc. - DocOnce has
strong support for such boxes and many alternative layouts,
in some formats, especially LaTeX,
HTML, and Sphinx). In this particular case we also specify blue
headings and blue-and-white rows in tables.
Blocks of computer code is typeset with the Pygments tool
(--latex_code_style=pyg) through the LaTeX package
minted.
By default, the standard LaTeX abstract environment is used for the
initial summary/abstract. It is easy to change the generated LaTeX
code, either manaully or (better!) by editing commands (recall that
manual edits are overwritten by a new DocOnce compilation while
editing commands can be embedded in a compilation script and rerun).
As an example, supposed you want to replace the abstract environment
by a quote environment with a smaller font. Automatic editing is
offered by the doconce replace command (direct text replacement):
doconce replace 'begin{abstract}' 'begin{quote}\small' report.tex
doconce replace 'end{abstract}' 'end{quote}' report.tex
More sophisticated automatic editing of the generated text from
doconce format can make use of doconce subst, which performs edits
via regular expressions. In this way, one can tailor the LaTeX
source (or HTML, Sphinx, whatever source) to special needs for
a document.
The next task is to run LaTeX on the generated report.tex
file (and BibTeX on the generated papers.bib):
rm -f report.aux
# Run pdflatex: the pygments environment for code requires
# use of the -shell-escape option
pdflatex -shell-escape report
bibtex report
pdflatex -shell-escape report
We can also make a PDF file for printing,
where linked URLs appear as footnotes
(the DocOnce source is of course the same).
The option --device=paper makes all URLs appear as footnotes, which
makes them visible in a paper version (they are still clickable in
the text, but the link text is in black, as the rest of the text - the
footnote superscript indicates the word to be clicked).
doconce format pdflatex report --device=paper \
--latex_admon=graybox1 --latex_font=palatino \
--latex_title_layout=titlepage \
--latex_code_style=pyg
rm -f report.aux
pdflatex -shell-escape report
bibtex report
pdflatex -shell-escape report
DocOnce can generate LaTeX for A4 or A6 paper size, if desired. The A6
size is good for smart phones, see the PDF file (made from DocOnce source). In this versiond we also change the
LaTeX font to Palatino (--latex_font=helvetica is another
possibility).
doconce format pdflatex report --latex_papersize=a6 \
--latex_font=palatino --latex_code_style=pyg
rm -f report.aux
pdflatex -shell-escape report
bibtex report
pdflatex -shell-escape report
PDF with yellow background in code blocks (made from LaTeX source generated from DocOnce source).
doconce format pdflatex report --latex_papersize=a4 --latex_font=helvetica --latex_code_style=lst-yellow2
rm -f *.aux
pdflatex report
bibtex report
pdflatex report
The Sphinx documentation system is very popular for creating online documents with fancy and attractive layouts. Check out the author's favorite themes: alabaster, bizstyle, bootstrap, bloodish (or cbc), fenics_minimal1, pyramid, redcloud, and scipy_lectures.
Sphinx default layout made from Sphinx-extended reStructuredText source generated from DocOnce. Other Sphinx layouts are ADCtheme, agni, agogo, alabaster, basic, basicstrap, bizstyle, bloodish, boilerplate, bootstrap, cbc, classic, cloud, dark, default, epub, fenics, fenics_classic, fenics_minimal1, fenics_minimal2, flat, haiku, jal, minimal5, modern5, nature, pylons, pyramid, redcloud, responsive, scipy_lectures, scrolls, slim-agogo, sphinxdoc, sphinx_rtd_theme, traditional, uio, uio2, vlinux-theme
DocOnce can easily generate a lot of various Sphinx layouts (see all
the names above). For layout X (pyramid, redcloud, etc.) one writes
doconce format sphinx report
doconce sphinx_dir theme=X report
python automake_sphinx.py
Sphinx documents need a special directory, by default called sphinx-rootdir,
which is automatically generated by the doconce sphinx_dir command.
The automatically generated
automake_sphinx.py script (by the doconce sphinx_dir command)
copies necessary files to the Sphinx
directory and runs the necessary commands to compile the Sphinx
document to HTML format.
HTML with the blueish style made from DocOnce source (see HTML code)
doconce format html report
HTML with the blueish2 style (same as blueish style unless pygments is turned off, then the code style is different, and admonitions has apricot default background color) made from DocOnce source
doconce format html report --html_style=blueish2 --pygments_html_style=off
HTML with the bloodish style made from DocOnce source
doconce format html report --html_style=bloodish
HTML with tactile-black style made from DocOnce source
doconce format html report --html_style=tactile-black
HTML with tactile-red style made from DocOnce source
doconce format html report --html_style=tactile-red
HTML with rossant style made from DocOnce source
doconce format html report --html_style=rossant
HTML with Architects+Daughter Google font and the bloodish style made from DocOnce source
doconce format html report --html_style=bloodish --html_body_font=Architects+Daughter --html_heading_font=Architects+Daughter
HTML with Clicker+Script Google font and the bloodish style made from DocOnce source
doconce format html report --html_style=bloodish --html_body_font=Clicker+Script --html_heading_font=Clicker+Script
The solarized color style for online documents has received much attention. Below are some examples on DocOnce support for this color style.
HTML with with the solarized style made from DocOnce source
doconce format html report --html_style=solarized
HTML with with the solarized_dark style made from DocOnce source
doconce format html report --html_style=solarized_dark
HTML with with the solarized2_light style made from DocOnce source
doconce format html report --html_style=solarized2_light
HTML with with the solarized2_dark style made from DocOnce source
doconce format html report --html_style=solarized2_dark
HTML with with the solarized3_light style made from DocOnce source
doconce format html report --html_style=solarized3_light
HTML with with the solarized3_dark style made from DocOnce source
doconce format html report --html_style=solarized3_dark
HTML with with the solarized_box html template made from DocOnce source with a template file (slight edit of a DocOnce template)
doconce format html report --html_style=solarized --html_template=template_solarized_box_yellow.html
DocOnce supports a range of HTML styles based on the Bootstrap framework. Such styles are seen all over the Internet and have a lot of functionality, e.g., responsive pages for smart phones and large screens. Here are some Bootstrap-based HTML styles: plain bootstrap made from DocOnce source, bloodish, FlatUI, bluegray. And here are some Bootswatch styles: cosmo, journal, readable, cyborg.
style=bootstrap
doconce format html report --html_style=$style --pygments_html_style=default --html_admon=bootstrap_alert --html_output=report_${style} --keep_pygments_html_bg --html_code_style=inherit --html_pre_style=inherit
doconce split_html report_$style.html
The other style values are bootswatch_cosmo, bootswatch_journal,
bootswatch_readable, and bootstrap_bloodish (many more exist,
see doconce format --help and look for the option --html_style).
The dark bootswatch_cyborg style is generated by
style=bootswatch_cyborg
doconce format html report --html_style=$style --pygments_html_style=monokai --html_admon=bootstrap_alert --html_output=report_${style} --keep_pygments_html_bg --html_code_style=inherit --html_pre_style=inherit
doconce split_html report_$style.html
It is recommended to use this setting of the Pygments style (monokai)
for all the dark Bootswatch styles.
HTML Vagrant style made from DocOnce source with a template file
# Copy the style to the current working dir
cp -r /path/to/doconce/root/bundled/html_styles/style_vagrant/template_vagrant.html .
# Customize the template (perhaps easier in an interactive editor...)
doconce replace LogoWord 'DiffEq' template_vagrant.html
doconce replace withSubWord 'Project' template_vagrant.html
doconce replace '<a href="">GO TO 1</a>' '<a href="http://wikipedia.org">Wikipedia</a>' template_vagrant.html
doconce replace '<a href="">GO TO 2</a>' '<a href="http://wolframalpha.com">WolframAlpha</a>' template_vagrant.html
doconce subst '<!-- footer --> Here .+' 'H. P. Langtangen © 2014' template_vagrant.html
# TOC, TITLE and AUTHOR are not appropriate with HTML templates
cp report.do.txt report2.do.txt
doconce replace 'TITLE: ' '#TITLE: ' report2.do.txt
doconce replace 'AUTHOR: ' '#AUTHOR: ' report2.do.txt
doconce replace 'TOC: ' '#TOC: ' report2.do.txt
doconce format html report2 --html_style=bootstrap --html_template=template_vagrant.html
HTML Bootstrap style with fixed toc made from DocOnce source with a template file
# Copy the style to the current working dir
cp -r /path/to/doconce/root/bundled/html_styles/style_bootstrap_wtoc/template_bootstrap_wtoc.html .
# Customize the template (perhaps easier in an interactive editor...)
doconce replace LogoWord 'DiffEq' template_bootstrap_wtoc.html
doconce replace withSubWord 'Project' template_bootstrap_wtoc.html
doconce replace '<a href="">GO TO 1</a>' '<a href="http://wikipedia.org">Wikipedia</a>' template_bootstrap_wtoc.html
doconce replace '<a href="">GO TO 2</a>' '<a href="http://wolframalpha.com">WolframAlpha</a>' template_bootstrap_wtoc.html
doconce subst '<!-- footer --> Here .+' 'H. P. Langtangen © 2014' template_bootstrap_wtoc.html
# TOC, TITLE and AUTHOR are not appropriate with HTML templates
cp report.do.txt report2.do.txt
doconce replace 'TITLE: ' '#TITLE: ' report2.do.txt
doconce replace 'AUTHOR: ' '#AUTHOR: ' report2.do.txt
doconce replace 'TOC: ' '#TOC: ' report2.do.txt
doconce format html report2 --html_style=bootstrap --html_template=template_bootstrap_wtoc.html --pygments_html_style=none
# Note: pygments code typesetting interferes with MathJax for this style,
# so we turn off pygments (which means plain <pre> tags for code blocks)
HTML (modified) GitHub minimal style made from DocOnce source with the GitHub minimal theme template (this template is best suited for a contents pages and not a full report)
# Copy the style to the current working dir
cp -r /path/to/doconce/root/bundled/html_styles/style_github_minimal .
# Make sure the css and js directories are local
mv style_github_minimal/css/* css/
mv style_github_minimal/js .
# Tailor headings in the template to this project
doconce replace 'Main Permanent Header' 'Project Report' style_github_minimal/template_github_minimal.html
doconce replace 'Permanent SubHeader' 'A Differential Equation Problem' style_github_minimal/template_github_minimal.html
cp report.do.txt report2.do.txt
doconce replace 'TITLE: ' '#TITLE: ' report2.do.txt
doconce replace 'AUTHOR: ' '#AUTHOR: ' report2.do.txt
doconce replace 'TOC: ' '#TOC: ' report2.do.txt
doconce format html report2 --html_template=style_github_minimal/template_github_minimal.html
# HTML code is in report.html; it needs the .png figures
# and the css and js directories
HTML plain Markdown style made from Markdown generated from DocOnce source
doconce format pandoc report
doconce subst '% .*' '' report.md # remove title, author, etc. (does not work well)
doconce md2html report
One would expect to use the pandoc program to transform the
report.md file in Markdown format to HTML, but doconce md2html
performs some additional hacks to get the mathematics to be rendered
correctly.
IPython notebook made from IPython notebook .ipynb file generated from DocOnce source
doconce format ipynb report
# Put report.ipynb on the web, e.g.,
# hplgit.github.com/teamods/writing_reports/_static/report.ipynb and
# then use the following URL to get the notebook rendered in a browser:
# http://nbviewer.ipython.org/url/hplgit.github.com/teamods/writing_reports/_static/report.ipynb
MediaWiki made from MediaWiki format generated from DocOnce source
doconce format mwiki report
cp report.mwiki /some/path/to/my/username.github.com.wiki/Experiments-with-Schemes-for-Exponential-Decay.mediawiki
For reports without mathematics, DocOnce can also generate Googlecode
wiki format (used at code.google.com)
and the Creole wiki format (used at bitbucket.org).
Google blog post at doconce.blogspot.com based on on HTML code generated from DocOnce source
cp report.do.txt report2.do.txt
# Remove title, author and date
doconce subst -m '^TITLE:.+$' '' report2.do.txt
doconce subst -m '^AUTHOR:.+$' '' report2.do.txt
doconce subst -m '^DATE:.+$' '' report2.do.txt
# Figures must have URLs to where they are stored on the web
site="https://raw.github.com/hplgit/hplgit.github.com"
dir="/master/teamods/writing_reports/_static"
for figname in BE FE CN error; do
doconce replace "[$figname," "[$site/$dir/$figname.png," report2.do.txt
done
doconce format html report2
# Paste report2.html text into a new blog on your Google account
Wordpress blog post at doconcereportdemo.wordpress.com based on HTML code generated from DocOnce source
doconce format html report2 --wordpress
# Paste report2.html into a new blog post on Wordpress
Bibliographic references in DocOnce files make use of information in Publish database. Either you have your references already
in the Publish format, or you can transform a BibTeX file refs.bib to
Publish format by
publish import refs
This creates a file papers.pub that acts as the Publish database
(one can easily assign other filenames to the database).
Such a .pub file looks as follows:
* books
** A Primer on Scientific Programming With {P}ython
key: Langtangen_2012
author: H. P. Langtangen
year: 2012
publisher: Springer
status: published
edition: Third
entrytype: book
** A First Course in the Numerical Analysis of Differential Equations
key: Iserles_2009
author: A. Iserles
year: 2009
publisher: Cambridge University Press
status: published
edition: Second
entrytype: book
The reason why DocOnce applies Publish is that it is easy to export Publish references to BibTeX, HTML, reStructuredText, pure ascii, etc.