Contributions need to be made via GitHub: https://github.com/ialbert/biostar-handbook-web
The web pages are generated with the pyblue static site generator from the git repository above. Install pyblue:
pip install pyblue
To serve the site on localhost run make
in the repository. This will
start the pyblue server instance and will serve the pages
make
Visit http://localhost:8080
to see the site.
Restart the server if you add a new file as the directory tree is scanned only once on startup. Changes to files however will be visible right away.
Book chapters and web pages are complementary. The content on the web needs to provide complete instructions that can be executed when copy pasted into a terminal.
Book chapters should focus on background and big picture explanations.
To create a new book chapter add it to the book
directory
then open a new issue for it. We'll use that issue to discuss
that chapter.
To create a new web page add it to the www/unit
directory with a filename
that starts with three digits: i.e. 123-vcf-format.html
The three initial
digits are used to order the sections in the table of contents.
All book chapters should be written in Markdown. A few guidelines:
- Provide a high level overview and context
- Keep the information short and relevant.
- Explain command settings only for essential, meaningful and challenging steps. The website will contain all commands that form a full pipeline.
- Explain thought processes, parameter choices and tacit assumptions.
- Talk about typical problems, errors and their solutions.
- Spend time explaining how to interpret the results.
- Use realistic (published) datasets that can be download either from this website or the SRA (fastq-dump).
- Reduce datasets to be processable on a MacBook Air in short amounts of time (30 minutes max) For example: subselect data for just one short chromosome for human genomes
- Don't add data to the github repository, send a link to the data to the maintainer
and they will move it to the
www/data
directory of the main site.
Each book chapter typically has at least on web unit associated with it.
Web units are stored in the www/unit
directory.
- Web units need to contain all commands used to generate a result.
- Comments should be used to explain the purpose of each command
- A web unit can be a plain HTML file, may contain markdown as well as Django Templating specific commands.
- Start with the example.html file in the repository. Now examine how this file gets rendered at http://biostarhandbook.com/unit/example.html
- Code can be embedded into pages (will be automatically syntax highlighted) or can be linked to as a file.
- Bootstrap 2.3 styling is enabled.
You can also consult the pyblue documentation for more details.