home | codereading | contact | math | misc | patches | tech
This is the README page of the site pointed by silas.net.br. If you are seeing this page from this URL, you are seeing the HTML rendered version. But if you are seeing it at its github repository, you are seeing the reStructuredText version.
Basically, this site is built using reStructuredText and converted to HTML using the docutils processing system. Its building system is made on the top of NetBSD make.
In summary, this website follows what is known as semi-static (or semi-dynamic) website. In this concept, the HTTP server deal with plain HTML files, that means that it doesn't deal with code that is dynamically generated. Dynamic sites use languages like PHP to generate HTML at the request moment.
Semi-dynamic websites have their HTML content generated from other files at a specific time and make those files available for the HTTP server, so this server only have to deal with plain HTML files.
The advantages (or disadvantages) or this technique is not the focus here. Anyway, the concept adopted on this site was inspired by the NetBSD website source, which is worth to have a look.
On the top of the source (where this file belongs to), there are some directories and subdirectories with RST files. There is one special directory, though, that is share/, that holds all logic about building.
For every (or almost every) directory, there is a Makefile that tell the build system what to make with each file or subdirectory in the current directory. So, this is the Makefile for the notes/unix/ directory at the time of I write this:
RSTDOCS = dec-tips.rst SUBDIR = linux SUBDIR += netbsd SUBDIR += x11 .include "../../share/mk/web.site.mk"
Here, the SUBDIR variable is a list of subdirectories that should be analyzed. The RSTDOCS variable holds a list of the files that should be compiled from RST to HTML. Finally we include the share/mk/web.site.mk file (the core of the building system), passing its relative path.
Possible variables for Makefiles like those are:
List of files to be compiled from RST to HTML.
It is important to point that all generated HTML files are post-processed to have some files references fixed. This site is entirelly written in reStructuredText files that will be converted to HTML files. So, how a file should refer to another file of this website? To the original RST file or the resulting HTML file?
The answer is: to the RST file. After calling rst2html, the resulting HTML is post-processed to make some substitutions, like converting all links to RST files to the resulting HTML file.
This is done to prevent just-in-time RST renderers to refer to non-existent HTML files, like GitHub one.
The RSTDOCS also accepts files which extension is .rst.nw, i.e., files that are actually noweb files and should be preprocessed first to generated .rst files. It is important to note that some substitutions can be made.
The redirect framework allows one page to get redirect to another page. It is useful mainly for renames when the old link is already spread over the web. One should use RENAME_RULES variable to add rules and RENAME.x.NEW and RENAME.x.OLD variables to add the source and the target of the redirection. For instance:
RENAME_RULES = busybox RENAME.busybox.NEW = notes/linux/busybox-troubleshooting.html RENAME.busybox.OLD = doc.notes/unix/linux/busybox-troubleshooting.html RENAME_RULES += xen RENAME.xen.NEW = notes/xen/xen-setup-netbsd.html RENAME.xen.OLD = doc.notes/xen/xen-setup-netbsd.html
In this example, we define two files on the old doc.notes directory should have redirect instructions to the new files on notes directories. See the redirect.mk file inside share/mk directory of this website source for more information.
The notangle framework process .rst.nw files to extract source code embeded in page. It uses the notangle tool from noweb. Like RENAME_RULES, you should use it and its helper variables:
NOTANGLE_RULES = osdev-inc NOTANGLE.osdev-inc.INPUT = osdev-inc.rst.nw NOTANGLE.osdev-inc.DESTDIR = osdev-inc-code NOTANGLE.osdev-inc.TARBALL = osdev-inc-code.tar.gz NOTANGLE.osdev-inc.CHUNKS += mbr1/mbr1.S NOTANGLE.osdev-inc.CHUNKS += mbr1/Makefile NOTANGLE.osdev-inc.CHUNKS += mbr1/run.sh
In this example, it will process osdev-inc.rst.nw files and extract mbr1/mbr1.S, mbr1/Makefile and mbr1/run.sh files inside osdev-inc-code directory. It will also generate a osdev-inc-code.tar.gz tarball. For more information, see the notangle.mk file.
First, clone this website from its github repository:
$ git clone git://github.com/silasdb/www.git
If the git protocol is blocked, use HTTP instead:
$ git clone https://github.com/silasdb/www.git
For building, you will need docutils, NetBSD make and noweb. If you run GNU/Linux or other non-NetBSD operating system, there is a portable version called bmake which is where that link will just guide you to.
Since you have NetBSD make and docutils installed -- and both make (or bmake, if you run non-NetBSD) and the rst2html program from docutils are in your $PATH, cd to the www directory and compile it:
$ cd www/ $ make # or bmake, on Non-NetBSD