17.18. GUIDE TO SYSTEM FOR OPEN SOURCE DEVELOPERS

The following guide has been written to help those wishing to adapt this system. Modifying the system can be quite a large task, especially in setup. We are not releasing the full package of files for automated generation process, as this includes personal login data to networks, etc. However, we do want to share this project as much as possible, therefore this guide has been written for those wish to take the time to adapt the system. If you are wanting a local copy of the files to host on your local network, or wish to clarify or add something to the guide below, please contact [Jack Morgan](mailto:jack.morgan%40canterbury.ac.nz). The guide is definitely not complete in it’s current state, but is being expanded frequently. The textbook is licensed under a Creative Commons Attribution Non-Commerical Share Alike license. Full details on this license, including a human readable summary, [can be found here](http://creativecommons.org/licenses/by-nc-sa/3.0/). Note Code experience recommended The following guide to setup your own Sphinx system is quite code heavy, so moderate experience with programming is recommended. For those who get stuck with Sphinx creation, the Sphinx community is very active, you can [find them here](https://groups.google.com/forum/?fromgroups=#!forum/sphinx-users). ## 17.18.1\. PROCESS OF TEXTBOOK CREATION[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#process-of-textbook-creation "Permalink to this headline") The textbook uses a documentation generator by the name of [Sphinx](http://sphinx-doc.org/), orginally created to generate Python documentation. [](http://csfieldguide.org.nz/_images/A-system-process.png) The textbook is written in a notation called ReStructured Text (or ReST), which acts much like a relaxed version of LaTeX. Details on how to use the ReStructured Text markup (plus how it fits into Sphinx) can be [found here](http://sphinx-doc.org/rest.html). The advantages of using the ReST format, is that if we ever want to switch away from the Sphinx system, we can plug the source material straight into the new system with minimal configuration. Most pages on the textbook website (except for a couple of special cases: homepage etc) are written in the ReST format, and you can view the source code by clicking the ‘Show Source’ link in the sidebar. For example, the source for this page can be found in the sidebar. The Sphinx system then processes these files, and generates the relevant HTML requires for the website. From this stage onwards, many tweaks have been made to the system, the source and the generation process to produce the material we wanted. These details are too numerous to go into detail about, however some good links to read for running your own Sphinx setup include: * [First Steps with Sphinx](http://sphinx-doc.org/tutorial.html) * [Sphinx Markup Constructs](http://sphinx-doc.org/markup/index.html) * [Sphinx Configuration File](http://sphinx-doc.org/config.html) * [HTML Theming](http://sphinx-doc.org/theming.html) * [Build Options](http://sphinx-doc.org/invocation.html) * [Available Sphinx Builders](http://sphinx-doc.org/builders.html) (What is produced on the generation: HTML, PDF etc) * [Math support in Sphinx](http://sphinx-doc.org/ext/math.html) ## 17.18.2\. VERSIONING[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#versioning "Permalink to this headline") For this textbook, several versions were created for different purposes. To designate content to different versions, we decided the student version would be the base version, as other versions *build* on top of this. Adding and designating content to another version (for example: a teacher’s note) is done with the [only command](http://sphinx-doc.org/markup/misc.html#directive-only) in the text files. The versions we created are as follows: * Student’s version * Teacher’s version (include comments for teachers) * Development version (includes raw development material) And each version are created in the following types: * Website (HTML output) * Paper (LaTeX/PDF output) * Portable (ePub/MOBI output) using an experimental builder You would generally create all the versions from the same source files (ie student version would just not include teachers notes), however we wanted to customise the website even further. Our textbook is generated by *one* system, from *one* main source and *three* minor sources (one for each version) into *multiple* outputs. The minor sources include files that needed to be different for each version. Some of these files include the Sphinx Configuration file ([conf.py file](http://sphinx-doc.org/config.html)) which dictated the appearance for the seperate versions (teacher version is green while student version is blue), and what was included in the sidebar (hiding the source files from students to prevent them from easily being able to access answers). This proved to be quite a complicated system to setup, however the system now has an extreme amount of power in customisation ability. ## 17.18.3\. PDF GENERATION[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#pdf-generation "Permalink to this headline") Guide on PDF generation to be released at a later date (when it’s ready). ## 17.18.4\. EPUB/MOBI GENERATION[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#epub-mobi-generation "Permalink to this headline") Guide on ePub/MOBIgeneration to be released at a later date (when it’s ready). ## 17.18.5\. HOW TO ADD CONTENT[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#how-to-add-content "Permalink to this headline") Guide on how to add content to be released at a later date (when it’s ready). ## 17.18.6\. UPDATE SCRIPT[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#update-script "Permalink to this headline") Guide on the update script to be released at a later date (when it’s ready). ## 17.18.7\. VISUAL APPEARANCE/CSS[](http://csfieldguide.org.nz/appendices/Open%20Source%20Guide.html#visual-appearance-css "Permalink to this headline") Guide on editing the appearance of the site to be released at a later date (when it’s ready).