Contents
Colophon¶
How this site came to be developed and tested on
$ uname -a
Linux 5.2.17-200.fc30.i686 #1 SMP Mon Sep 23 13:43:18 UTC 2019 i686 i686 i386 GNU/Linux
History¶
Original text content in markdown format was copied from the Prism app content repository develop branch. Images came from PrISM app assets repository develop branch.
The original electron app was developed with the intent of publishing this content inside the app. The app worked great, however required an annual fee for authentication and required end users to install a special app on their computers.
This document is the tutorial content liberated from the app.
Multi-step process¶
Converting multiple markdown pages into an organized website.
markdown -> Pandoc -> reStructuredText -> Sphinx -> html -> Github -> read-the-docs
Pandoc¶
- Converting from markdown to reStructuredText requires the installation and running of Pandoc.
- Command line syntax generic
pandoc -s -t rst --toc $source -o $target
where:$source=~/workspace/PrISM-read-the-docs/content
$target=~/workspace/PrISM-read-the-docs/conversions/source
- Pandoc copies from .md
/content
and converts into .rst/source
reStructured Text¶
reStructuredText has an .rst suffix.
Pandoc outputs the .rst files to:
~/workspace/PrISM-read-the-docs/conversions/source
Currently the
/conversion/source/*.rst
files are the result of a scripted conversion from the markdown and should not be edited directly.
Conversion to html¶
Conversion to html requires the installation and running of Sphinx a python based document generator.
Change into the
/conversions
directory, which also has (or will have) the Makefile.$ cd ~/workspace/PrISM-read-the-docs/conversions/
One time only, to generate some sphinx defaults
$ sphinx-quickstart
Command line syntax generic:
$ sphinx-build -b html source build
Command line syntax specific to this project:
$ sphinx-build -b html \
~/workspace/PrISM-read-the-docs/conversions/source \
~/workspace/PrISM-read-the-docs/conversions/build
Sphinx expects an
index.rst
file that dictates the table of contents. In this project the index did not exist previously, and was therefor created in the/source
directory, and outlined in a way that seemed to mimic the numbering of the original markdown documents.
The transformed output build documents are served as a web page something like:
$ firefox ~/workspace/PrISM-read-the-docs/conversions/build/index.html
Workspace customization¶
Install Pandoc. On Fedora linux it might look something like:
$ sudo dnf install pandoc
Install python virtual environment something like:
$ pip3 install virtualenv
Create a virtual environment for the project
$ cd ~/workspace/PrISM-read-the-docs/conversions/
$ virtualenv venv
Enable the python virtual environment
$ cd ~/workspace/PrISM-read-the-docs/conversions/
$ source ./venv/bin/activate
Install Sphinx
$ cd ~/workspace/PrISM-read-the-docs/conversions/
$ pip3 install -U sphinx
Github¶
This documentation can be accessed at github.com/NorthwestGreenChemistry/PrISM-read-the-docs something like:
$ git clone https://github.com/NorthwestGreenChemistry/PrISM-read-the-docs.git
and once the edits are done push back to the repository
$ git remote add origin
`https://github.com/NorthwestGreenChemistry/PrISM-read-the-docs.git `
$ git push -u origin develop
Read-the-docs¶
“Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you. Think of it as Continuous Documentation.”
Write the recommended
readthedocs.yml
configuration file into the root directory of the project. For example$ touch ~/workspace/PrISM-read-the-docs/readthedocs.yml
$ git push
the repository to Github.Sign in to the read-the-docs account to administer the configuration.
View the resulting documentation at prism.readthedocs.io
Misc important stuff¶
The original links paths to assets such as images were hard coded in the app where the In this document the hard coding have been deleted and replaced with relative paths. This means the location of the asset directory matters relative to
/source
. The assets directory was manually copied once into/source
to allow Sphinx to easily find the assets./conversions |- /source/ assets (content .rst files) |- /build
In order for the github repository to accurately render the markdown pages with images the
/assets
directory must be moved into the/content
directory./content |- /assets /conversions
Markdown is great for simple docs, however reStructuredText meets the challenges of more complex documents, including features like table of contents and indexing. If this Sphinx document format is marketable, it may make sense in a future revision to move away from markdown to only use the reStructuredText.
Bash script for editing automation¶
There is a bash script written just for this project to allow the conversion process to be repeated during editing of the markdown files.
script
- location:
$ cd ~/workspace/PrISM-read-the-docs/conversions/
- filename:
convert-md-to-rst-to-html.sh
running the script
- Make the script executable
$ chmod 744 convert-md-to-rst-to-html.sh
- make some edits to the markdown in
/content
- run the script in
/conversions
like this:$ ./convert-md-to-rst-to-html.sh