The whole QuantumOptics.jl website is created from different parts:
- QuantumOptics.jl-examples provides all the examples that are used and linked to in the documentation. They are created using jupyter notebooks and executed and converted to markdown with nbconvert. This markdown code is then copied to QuantumOptics.jl-documentation. Additionally, it provides the codesnippets that are used on the main page of the website.
- QuantumOptics.jl-documentation is written with markdown. Documenter.jl is used to integrate the docstrings from QuantumOptics.jl and to generate html code which includes the examples from QuantumOptics.jl-examples.
- QuantumOptics.jl-benchmarks generates json files containing the results of the benchmarks and provides the source code of the examples.
In this repository the following additional resources are defined:
- A common header used in every single page.
- A common navigation menu (on the top of each page).
- A common footer.
- The main page.
- QuantumOptics.jl code snippets which are shown in the main page.
- Citation page.
- Benchmark page presenting the data and source-code obtained from QuantumOptics.jl-benchmarks
Jekyll is used to generate the (static) website from all different parts.
The website itself uses the following technologies:
- Bootstrap.js for the layout.
- MathJax.js for representing latex formulas.
- highlight.js to dynamically highlight the source code.
- Chart.js for the interactive benchmark plots.
A basic principle is that any code that is shown should be run and tested automatically before it is included.
It is recommended to place all resources into the same directory, i.e.:
| |--> ./QuantumOptics.jl |--> ./QuantumOptics.jl-examples |--> ./QuantumOptics.jl-documentation |--> ./QuantumOptics.jl-benchmarks |--> ./QuantumOptics.jl-website
The complete build process of all resources and the website itself can be done with
This script runs the following operations that can of course also be performed manually to obtain finer control over the build process:
- All git repositories are updated with
- Convert notebooks in
QuantumOptics.jl-examplesinto markdown files and copy them to
- Build documentation in
QuantumOptics.jl-documentationand copy them into
- Copy results of benchmarks into
src/benchmark-dataand their source code into
- Run code snippets (which then are shown in the main page) with
Finally, one uses jekyll to build website:
* For development run jekyll interactively:
* To just create it once:
This will create the finished website in the
build directory which then can be deployed to the server.