G-Loaded Journal » Documentation http://www.g-loaded.eu An open-source software and technology related journal Mon, 05 Dec 2011 19:55:24 +0000 en hourly 1 http://creativecommons.org/licenses/by-nc-sa/3.0/ How to create a single file of Sphinx based documentation http://www.g-loaded.eu/2010/10/29/sphinx-documentation-single-file/ http://www.g-loaded.eu/2010/10/29/sphinx-documentation-single-file/#comments Fri, 29 Oct 2010 17:17:13 +0000 George Notaras http://www.g-loaded.eu/?p=2073 It has become common nowadays that Python projects provide their documentation in “source form“. The documentation is split into multiple files, written in restructured text, and is shipped together with some other configuration and media files for Sphinx. The user is meant to use the provided Makefile to export the documentation in various formats. This is good and useful. Sphinx generates some nice and very readable HTML files. The only problem I encountered today was that the provided Makefile or make.bat batch script (for Windows) cannot be used to generate a single file containing the whole documentation of the project. At first, it seemed that in order to print the whole documentation I should either:

  • export the documentation into multiple HTML files using make html and then send the relevant html files one-by-one to the printer, which is insanely inconvenient, or
  • export the documentation to LaTeX format and then use a tex-to-pdf converter in order to merge the documentation files into a single file, which I would finally send to the printer. It should be noted that in this case, the tex-to-pdf converter had some other dependencies which summed up to 130+MB. Compressed. That’s insanely too much for converting the documentation to single-file form!!!

So, I ended up using grep to scan the sphinx source code for expressions like single, single file etc. I soon hit singlehtml! Fortunately, there is a builder, named singlehtml, that produces a single HTML document for documentation that is split into multiple files. Hooray!!

I used the sphinx-build utility directly to generate a single HTML document containing the entire documentation. After changing to the documentation’s root directory, I issued the command:

sphinx-build -b singlehtml . zzz

I finally had a single HTML file at zzz/index.html, which I sent to the printer and got some nice documentation in-print.

How to create a single file of Sphinx based documentation, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2010/10/29/sphinx-documentation-single-file/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/ OpenSolaris ZFS Screencasts and Documentation Links http://www.g-loaded.eu/2009/04/12/opensolaris-zfs-screencasts-and-documentation-links/ http://www.g-loaded.eu/2009/04/12/opensolaris-zfs-screencasts-and-documentation-links/#comments Sun, 12 Apr 2009 17:25:14 +0000 George Notaras http://www.g-loaded.eu/?p=1064 This post incudes a list of ZFS related screencast links and documentation links that you might find useful.

Here is a list of screencasts that go through the use of ZFS on OpenSolaris:

Also, here are some useful links to documentation:

Of course, I haven’t been through all of them… Well, I am not a professional sysadmin after all :) What I tried to do to create is a small collection of screencasts and documentation links that a curious FOSS user would find useful.

OpenSolaris ZFS Screencasts and Documentation Links, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2009/04/12/opensolaris-zfs-screencasts-and-documentation-links/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/ Security Guides for Operating Systems by the NSA http://www.g-loaded.eu/2007/12/16/security-guides-for-operating-systems-by-the-nsa/ http://www.g-loaded.eu/2007/12/16/security-guides-for-operating-systems-by-the-nsa/#comments Sun, 16 Dec 2007 11:59:21 +0000 George Notaras http://www.g-loaded.eu/2007/12/16/security-guides-for-operating-systems-by-the-nsa/ The National Security Agency (NSA) of the USA has published some security configuration guides for various popular Operating Systems. Linux is covered by the Red Hat Enterprise Linux 5 security guide, but most of the included information can be easily translated to other Linux distributions. As it is clearly stated in the guide’s disclaimer, all the included information only constitutes “recommended security changes” and not changes that should be made to all OS setups. Anyhow, even from the quick look I had inside, I can say that this is professional work. This document is an excellent read regardless of the Linux distribution you use. Guides for other operating systems, such as Microsoft Windows, Apple MacOS X, Sun Solaris 8/9, exist as well. I learned about these guides while browsing the mailing list archives of the Fedora Documentation Project (FDP) some days ago, so all credit goes to the person who posted it there in the first place.

Security Guides for Operating Systems by the NSA, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2007/12/16/security-guides-for-operating-systems-by-the-nsa/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/ Print a Man Page http://www.g-loaded.eu/2007/03/05/print-a-man-page/ http://www.g-loaded.eu/2007/03/05/print-a-man-page/#comments Mon, 05 Mar 2007 15:22:36 +0000 George Notaras http://www.g-loaded.eu/2007/03/05/print-a-man-page/ Reading a man page using a terminal application is easy, but I doubt if it would ever win a convenience award. Sometimes, it is necessary to print the man page. I can recommend two ways of doing this.

First, using the -t switch, when launching the man command from a terminal, causes the man page to be formatted in Postscript. Technically, it uses groff to perform the conversion. More information about this can be found within the man command’s manual page (man 1 man).

The Postscript output can be piped to lpr for printing in a CUPS printer. The following example prints the iptables manual page to the HP690C printer:

$ man -t iptables | lpr -P HP690C

Alternatively, the output can be saved to a postscript file:

$ man -t iptables > iptables.ps

More on using a CUPS printer from the CLI can be found here.

Those who have the Yelp GNOME application installed, can take advantage of its internal man page parser and HTML converter. For example, in order to display the iptables man page in Yelp, launch it like the following:

$ yelp man:iptables

From there, you can use the GNOME print dialog to print the iptables manual.

I tend to prefer the quality of the man page when it has been printed through Yelp.

Print a Man Page, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2007/03/05/print-a-man-page/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/ LaTeX links for the absolute beginner http://www.g-loaded.eu/2006/11/27/latex-links-for-the-absolute-beginner/ http://www.g-loaded.eu/2006/11/27/latex-links-for-the-absolute-beginner/#comments Mon, 27 Nov 2006 12:31:03 +0000 George Notaras http://www.g-loaded.eu/2006/11/27/latex-links-for-the-absolute-beginner/ Today, I stumbled upon the following links, which seem to be what could get someone started with LaTeX. Andrew Roberts has done an exceptional job. His tutorials cover topics both for the absolute beginner and the medium experienced user. This is a must read! Actually, I found out about the above tutorials by this post, which contains an example of a book in LaTeX. Very interesting information.

LaTeX links for the absolute beginner, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2006/11/27/latex-links-for-the-absolute-beginner/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/ Epiphany Python Console – Documentation http://www.g-loaded.eu/2006/05/17/epiphany-python-console-documentation/ http://www.g-loaded.eu/2006/05/17/epiphany-python-console-documentation/#comments Wed, 17 May 2006 11:22:40 +0000 George Notaras http://www.g-loaded.eu/2006/05/17/epiphany-python-console-documentation/ The availability of good and complete documentation for an API is one of the most important factors in order someone to be able to effectively use that API for application programming. Good API documentation saves time and effort. It provides all the needed information a programmer, either professional or amateur, would need in order to use the best routines to solve a problem.

Recently, I started messing with the Epiphany browser’s Python console. What I need is to write some extensions for this browser, so that it covers all my needs when browsing the internet. Despite my will to do so, the lack of decent documentation for the available Python bindings is very discouraging. Many of the available functions even lack a simple docstring. As I have already mentioned in earlier posts, I am not a pro. Even a very simple extension takes a significant amount of time and effort. Furthermore, even if I finally find a way to solve a problem, I still wonder if that was the best way I could go.

Anyway, this is how it is. For all those who would like to mess around with Epiphany’s Python console, here are the available docs:

These should get you started, but despite the writer’s great effort and contribution, these are not enough for an amateur programmer. You will still need to search in other extensions’ source code and probably in the Epiphany’s source too. This is the situation and I wish things get better in the future. So, I have decided that, whenever my free time permits it, I will write a post for every new thing I discover in the python console. Hope this helps someone else out there…

Epiphany Python Console – Documentation, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2006/05/17/epiphany-python-console-documentation/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/ Write A Man Page http://www.g-loaded.eu/2006/05/04/write-a-man-page/ http://www.g-loaded.eu/2006/05/04/write-a-man-page/#comments Thu, 04 May 2006 05:42:49 +0000 George Notaras http://www.g-loaded.eu/2006/05/04/write-a-man-page/ Some links about how to write a man page:

Last, but not least:

# man 7 groff_man

This man page contains all the macros that can be used in a manual page.

Write A Man Page, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Terms and conditions beyond the scope of this license may be available at www.g-loaded.eu.

Related Articles

]]> http://www.g-loaded.eu/2006/05/04/write-a-man-page/feed/ 0 http://creativecommons.org/licenses/by-nc-sa/3.0/