Organization of the VTKExamples Repository¶
All example source code, descriptions, test data and test baselines are stored in the src/ tree.
The major elements of the tree are:
|-- VTKExamples |-- CMakeLists.txt # To build all of the examples |-- _layouts # Contains _default.html |-- custom_theme # tweaks to material theme |-- mkdocs.yml # config file for MkDocs |-- src # all of the content to create site/ |-- SyncSiteWithRepo.sh # master script to update site/ |-- Admin | |-- ScrapeRepo # script to create docs/ | |-- VTKCMakeLists # template for Cxx examples | |-- VTKQtCMakeLists # template for Cxx Qt | |-- sitemap.xml # generated sitemap | |-- sitemapGenerator # site map generator |-- Artifacts # Additional images, docs, etc. |-- Instructions # Documentation |-- LANGUAGE.md # Summary file for language |-- LANGUAGE # Language examples | |-- TOPIC |-- Tarballs # Tar files for each Cxx example |-- Testing | |-- Baseline # Baselines for examples | | |-- LANGUAGE | | | |-- TOPIC | |-- Data # Data for examples |-- stylesheets |-- extra.css # mkdocs search config |-- site # static web pages generated by mkdocs
Look and Feel¶
A priority in moving from the wiki media VTK Wiki Examples to the github pages VTKExamples was to provide a modern, familiar look and feel. We also wanted to support tablet and mobile platforms. We chose MkDocs because it generated static html pages that can be hosted anywhere.
MkDocs is a python package and can be installed using
pip install mkdocs
The mkdocs.yml file contains the configuration parameters
site_name: VTKExamples theme: material site_url: https://lorensen.github.io/VTKExamples/site/ repo_name: lorensen/VTKExamples repo_url: https://github.com/lorensen/VTKExamples theme_dir: custom_theme markdown_extensions: - admonition - codehilite(guess_lang=false) - toc(permalink=true) google_analytics: - 'UA-3660134-4' - 'auto' extra_css: - 'stylesheets/extra.css' copyright: '<font color=#666>Content is available under </font><a href="https://creativecommons.org/licenses/by/2.5/" title="Attribution2.5">Attribution2.5</a> <font color=#666>unless otherwise noted.</font>'
A number of markdown extensions are available.
Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. For example:
This is a note or seealso admonition
This is a summary or tldr admonition
This is a info or todo admonition
This is a tip, hint or important admonition
This is a success, check or done admonition
This is a question,help faq admonition
This is a warning, caution or attention admonition
This is a failure, fail or missing admonition
This is a danger or error admonition
This is a bug admonition
This is a quote or cite admonition
This is a cite admonition
The codehilite extension highlights code depending on the language.
The toc extension generates a table of contents, like the one at the right of this page.
The Materials theme is built using Google's Material Design guidelines. It offers a unified experience across platforms. The look and feel is a familiar one.
The materials theme is selected using the material keyword in the mkdocs.yml file.
Google Analytics tracks the site usage, providing lots of useful statistics. To have Google Analytics track web usage you need to register the url with the Google Analytics System. After registration, an html snippet is provided to include on every web page to be tracked.
Configuring Google Analytics¶
The google_analytics keyword in the mkdocs.yml" file specifies the google analytics unique code for this web site. The custom_theme/main.html* file defines the meta data for the google site verification:
<meta name="google-site-verification" content="8hi6AHNlzKOmFDV4W8tLmySODRzQvtqMEIfZdc3WTLA" />
The overall look and feel is established at https://cse.google.com/cse/. After setting up the search engine, you can get the code to add to the web pages.
The code is added to custom_theme/main.html.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <gcse:searchbox-only>Search</gcse:searchbox-only>
The search box is added to the web pages by adding the gcse search box html
The first implementation had problems loading the Cxx summary. The number of embedded images exceeded the throttle limits of github. A lazy image load solution solved the problem. Now, images are only loaded if they appear in the browser window.
The VTKExamples web pages have many url's that link to images and VTK doxygen pages. The long length of these url's can increase page load tines, especially on the language summary pages.
http://tinyurl.com provides a service to map the long url's into shorted url's. There is a python package, tinyurl, that converts the long url's. Unfortunately, this process is slow. To speed up the process, we cache the long/short url's in a file src/Admin/TinyUrlCache. ScrapeRepo uses this cache to only convert url's that are not in the cache. ScrapeRepo updates the cache after each run.
tinyurl must be installed:
pip install tinyurl
Minify HTML pages¶
mkdocs generates HTML pages from the markdown files in doc. These pages have lots of white space. We use the python package htmlmin to compress the generated HTML. The compressed pages are abput 30% smaller after running htmlmin. We use the command line to process each index.html file in site/.
htmlmin must be installed:
pip install htmlmin
Given a RepositoryDir, DocDir and a RepositoryUrl, ScrapeRepo proceeds as follows:
Adds thumbnails to the Cxx.md and Python.md summary pages. A thumbnail is added if a src/Testing/Baseline/LANG/TOPIC/TestEXAMPLE.png image exists for the example.
Copies non-example .md files like Cxx.md and Python.md files to docs/.
For each example source file create docs/LANG/TOPIC/EXAMPLE.md file that contains:
- If src/Testing/Baseline/LANG/TOPIC/TestEXAMPLE.png exists add the image
- If a src/LANG/TOPIC/EXAMPLE.md description file exists, insert the description
- Insert the source code from src/LANG/TOPIC/EXAMPLE.EXTENSION
For each Cxx source file
- If Cxx/TOPIC/EXAMPLE.cmake exists, add it as the CMakeLists section of the .md file, otherwise, fill in the VTKCMakelists template, including the files listed in the optional src/Cxx/TOPIC/EXAMPLE.extras file.
For each Cxx source file, create a src/Tarballs/EXAMPLE.tar file containing the source and CMakeLists.txt file.
The SyncSiteWithRepo.sh shell script executes all of the steps to update the static website. It proceeds as follow:
Makes sure the site is up
Pulls updates from the master repository.
Pulls updates from the src/Tarballs repository
The tarballs are kept in a separate repository to reduce the size of the main repository. They are only accessed from the individual example pages.
Creates the coverage files
The src/Admin/VTKClassesUsedInExamples.py python script generates two tables for each language. One table list each class and what classes it uses. The second table lists the classes that are not used in any example.
Wipes the docs directory
The docs directory contains all of the md and html files for the site. A clean directory prevents old files from being used.
Runs the ScrapeRepo script
This will populate the docs directory.
Checks for a successful scrape
This sanity check sees if a reasonable number of files have been updated.
Copies the src/stylesheets directory ino docs/stylesheets
Copies the sitemap.xml file
This file is updated periodically by sitemapGenerator
Minify the html
Process any modified, added or deleted file
Update the tarballs
Push the changes
After a short time github will update the github pages.