Commit a7e68b8a authored by Andrew Maclean's avatar Andrew Maclean

Merge branch 'setup_website' into 'master'

Setup website

See merge request vtk/vtk-examples!8
parents a9c4db60 e7137f2e
# Change these to reflect the user and site details.
site_name: VTKEx
site_url: https://ajpmaclean.github.io/VTKEx/site/
repo_name: ajpmaclean/VTKEx
repo_url: https://github.com/ajpmaclean/VTKEx
site_name: web-test
site_url: https://ajpmaclean.github.io/web-test/site/
repo_name: ajpmaclean/web-test
repo_url: https://github.com/ajpmaclean/web-test
theme:
name: material
......
......@@ -35,15 +35,17 @@ def get_program_parameters():
parser = argparse.ArgumentParser(description=description, epilog=epilogue,
formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('repo_dir', nargs='?', default='src',
help='The local directory in the VTK Examples folder containing the source files e.g. src')
parser.add_argument('doc_dir', nargs='?', default='docs',
help='The directory to receive the markdown pages in the VTK Examples folder e.g. docs')
parser.add_argument('repo_url',
help='repo_url is the github repo URL e.g. https://github.com/**YOUR_NAME**/VTKExamples')
parser.add_argument('vtk_src', help='The local directory containing the VTK source')
help='The path to the folder containing the source files e.g. <local_path>/vtk-examples/src')
parser.add_argument('site_url', help='The source repository URL e.g. https://gitlab.kitware.com/vtk/vtk-examples')
parser.add_argument('web_site_url', help='The website URL e.g. https://<username>.github.io/<site_name>/site')
parser.add_argument('web_repo_url', help='The website source URL e.g. https://github.com/<username>/<site_name>')
parser.add_argument('web_repo_dir',
help='The path to the folder containing the web source files e.g. <local_path>/<site_name>')
parser.add_argument('vtk_src_dir', help='The local directory containing the VTK source')
args = parser.parse_args()
return args.repo_dir, args.doc_dir, args.repo_url, args.vtk_src
return args.repo_dir, args.site_url, args.web_site_url, args.web_repo_url, args.web_repo_dir, args.vtk_src_dir
# return args.repo_dir, args.web_path, args.web_url, args.vtk_src_dir
class ElapsedTime:
"""
......@@ -465,11 +467,11 @@ def get_example_line(s):
return ['']
def add_thumbnails_and_links(repo_url, root_path, repo_dir, doc_dir, baseline_dir, test_images, from_file, to_file,
def add_thumbnails_and_links(web_repo_url, root_path, repo_dir, doc_dir, baseline_path, test_images, from_file, to_file,
stats):
"""
Add thumbnails, and language links, then copy to the doc_dir.
:param repo_url: The repository URL.
:param web_repo_url: The repository URL.
:param root_path: Path to the top-level folder e.g. VTKExamples.
:param repo_dir: Usually 'src'.
:param doc_dir: Usually 'docs'.
......@@ -481,8 +483,8 @@ def add_thumbnails_and_links(repo_url, root_path, repo_dir, doc_dir, baseline_di
:return:
"""
from_path = make_path(root_path, repo_dir, from_file)
to_path = make_path(root_path, doc_dir, to_file)
baseline_path = make_path(root_path, repo_dir, baseline_dir)
to_path = make_path(doc_dir, to_file)
# baseline_path = make_path(root_path, repo_dir, baseline_dir)
with open(from_path, 'r') as md_file:
lines = dict()
line_count = 0
......@@ -498,7 +500,7 @@ def add_thumbnails_and_links(repo_url, root_path, repo_dir, doc_dir, baseline_di
example_dir = os.path.split(example_line)[0]
baseline = make_path(baseline_path, example_dir, "Test" + example_name + ".png")
if os.path.exists(baseline):
baseline_url = make_path(repo_url, "blob/master", "src", baseline_dir, example_dir,
baseline_url = make_path(web_repo_url, "blob/master", "src/Testing/Baseline", example_dir,
"Test" + example_name + ".png")
x[0] = True
x.append(baseline_url)
......@@ -537,38 +539,42 @@ def add_thumbnails_and_links(repo_url, root_path, repo_dir, doc_dir, baseline_di
ofn.write(line + '\n')
def fill_CMake_lists(cmake_contents, example_name, extra_names, vtk_module):
def fill_CMake_lists(cmake_contents, example_name, extra_names, vtk_modules, web_repo_url):
"""
Fill in the template parameters in a CMakeLists template file.
The output is a CMakeLists.txt file with Name substituted for {{{1}}}
:param cmake_contents: The template file.
:param example_name: The example file name.
:param extra_names: Any needed extra files needed to build the example.
:param vtk_module: The VTK module e.g. vtkCommonCore.
:param vtk_modules: The VTK modules e.g. vtkCommonCore ... in a string.
:param web_repo_url: The web repository URL.
:return: A CMakeLists.txt file.
"""
r1 = re.sub(r'XXX', example_name, cmake_contents)
r2 = re.sub(r'YYY', extra_names, r1)
r3 = re.sub(r'ZZZ', vtk_module, r2)
return r3
r1 = re.sub(r'WWW', web_repo_url, cmake_contents)
r2 = re.sub(r'XXX', example_name, r1)
r3 = re.sub(r'YYY', extra_names, r2)
r4 = re.sub(r'ZZZ', vtk_modules, r3)
return r4
def fill_Qt_CMake_lists(cmake_contents, example_name, vtk_module):
def fill_Qt_CMake_lists(cmake_contents, example_name, vtk_modules, web_repo_url):
"""
Fill in the template parameters in a CMakeLists template file.
The output is a CMakeLists.txt file with Name substituted for {{{1}}}
:param cmake_contents: The template file.
:param example_name: The example file name.
:param vtk_module: The VTK modules e.g. vtkCommonCore.
:param vtk_modules: The VTK modules e.g. vtkCommonCore ... in a string.
:param web_repo_url: The web repository URL.
:return: A CMakeLists.txt file
"""
r1 = re.sub(r'XXX', example_name, cmake_contents)
reg = re.sub(r'ZZZ', vtk_module, r1)
return reg
r1 = re.sub(r'WWW', web_repo_url, cmake_contents)
r2 = re.sub(r'XXX', example_name, r1)
r3 = re.sub(r'ZZZ', vtk_modules, r2)
return r3
def make_markdown_example_page(f, lang, lang_ext, root, available_languages, repo_path, doc_path,
kit_name, repo_name, repo_url, user_name, vtk_modules_dict, vtk_src_dir,
kit_name, repo_name, web_repo_url, user_name, vtk_modules_dict, vtk_src_dir,
example_to_file_names, example_to_CMake, code_to_page, stats):
"""
Here we make the markdown page for a given example.
......@@ -581,7 +587,7 @@ def make_markdown_example_page(f, lang, lang_ext, root, available_languages, rep
:param doc_path: The path to the docs.
:param kit_name: The kit name.
:param repo_name: The repository name.
:param repo_url: The repository URL.
:param web_repo_url: The web repository URL.
:param user_name: The user name.
:param vtk_modules_dict: The VTK modules dictionary.
:param vtk_src_dir: The VTK source directory.
......@@ -615,7 +621,7 @@ def make_markdown_example_page(f, lang, lang_ext, root, available_languages, rep
'[' + repo_name + '](/)/[' + lang + '](/' + lang + ')/' + kit_name + '/' + example_name + '\n\n')
if os.path.isfile(baseline_path):
image_url = repo_url + '/blob/master/src/Testing/Baseline/' + lang + '/' + kit_name + '/Test' \
image_url = web_repo_url + '/blob/master/src/Testing/Baseline/' + lang + '/' + kit_name + '/Test' \
+ example_name + '.png?raw=true'
# href to open image in new tab
md_file.write('<a href="' + image_url + ' target="_blank">' + '\n')
......@@ -718,7 +724,7 @@ def make_markdown_example_page(f, lang, lang_ext, root, available_languages, rep
needed_modules += '\n ' + vtk_module
else:
needed_modules += '\n ' + 'vtk' + vtk_module
cmake = fill_Qt_CMake_lists(CMake_contents, example_name, needed_modules)
cmake = fill_Qt_CMake_lists(CMake_contents, example_name, needed_modules, web_repo_url)
else:
with open(os.path.join(repo_path, 'Admin', 'VTKCMakeLists'), 'r') as CMakeFile:
CMake_contents = CMakeFile.read()
......@@ -729,40 +735,43 @@ def make_markdown_example_page(f, lang, lang_ext, root, available_languages, rep
needed_modules += '\n ' + vtk_module
else:
needed_modules += '\n ' + 'vtk' + vtk_module
cmake = fill_CMake_lists(CMake_contents, example_name, extra_names, needed_modules)
cmake = fill_CMake_lists(CMake_contents, example_name, extra_names, needed_modules, web_repo_url)
if lang == 'Cxx':
example_to_CMake[example_name] = get_VTK_CMake_file(cmake)
md_file.write(cmake)
code_to_page[example_name + lang_ext] = '/' + lang + '/' + kit_name + '/' + example_name
def make_instruction_pages(repo_url, root_path, repo_name, user_name, repo_dir, doc_dir, from_file, to_file):
def make_instruction_pages(web_repo_url, web_site_url, site_repo_url, root_path, repo_dir, doc_path, from_file, to_file):
"""
Make the instruction pages.
Note: In site_url, if you are not using github.io, change it appropriately.
Make the instruction pages. The keys in the dictionary patterns are used to replace the
corresponding keys in the instructions.
:param repo_url: The repository URL.
:param web_repo_url: The web repository URL.
:param web_site_repo_url: The web site URL.
:param site_repo_url: The URL corresponding to the source files repository.
:param root_path: Path to the top-level folder e.g. VTKExamples.
:param repo_name: The name of the repository.
:param user_name: The username for the repository.
:param repo_dir: Usually 'src'.
:param doc_dir: Usually 'docs'.
:param doc_path: Usually 'docs'.
:param from_file: The file to copy/edit
:param to_file: The save file name.
:return:
"""
src = make_path(root_path, repo_dir, 'Instructions', from_file)
dest = make_path(root_path, doc_dir, 'Instructions', to_file)
site_url = 'https://' + user_name + '.github.io/' + repo_name + '/site/'
patterns = {'__BLOB__': repo_url + '/blob/master',
'__TREE__': repo_url + '/tree/master',
'__REPOSITORY__': repo_url,
'__ARCHIVE__': repo_url + '/archive/master.zip',
'__GIT_REPO__': repo_url + '.git',
'__REPO_NAME__': repo_name,
'__USER_NAME__': user_name,
'__SITE__': site_url,
dest = make_path(doc_path, 'Instructions', to_file)
patterns = {'__BLOB__': site_repo_url + '/blob/master',
'__TREE__': site_repo_url + '/tree/master',
'__SITE_REPOSITORY__': site_repo_url,
'__ARCHIVE__': site_repo_url + '/archive/master.zip',
'__GIT_REPO__': site_repo_url + '.git',
'__REPO_NAME__': list(filter(None, site_repo_url.split('/')))[-1],
'__USER_NAME__': list(filter(None, site_repo_url.split('/')))[-2],
'__WEB_BLOB__': web_repo_url + '/blob/master',
'__WEB_SITE__': web_repo_url + '/site',
'__WEB_SITE_URL__': web_site_url,
'__WEB_REPOSITORY__': web_repo_url,
'__WEB_REPO_NAME__': list(filter(None, web_repo_url.split('/')))[-1],
'__WEB_USER_NAME__': list(filter(None, web_repo_url.split('/')))[-2],
}
keys = patterns.keys()
with open(src, 'r') as ifh:
......@@ -779,7 +788,7 @@ def make_instruction_pages(repo_url, root_path, repo_name, user_name, repo_dir,
ofh.write(line)
def make_tarballs(repo_path, example_to_file_names, example_to_CMake, ref_mtime):
def make_tarballs(repo_path, web_repo_dir, example_to_file_names, example_to_CMake, ref_mtime):
"""
Create tarballs for each example.
:param repo_path: Repository path.
......@@ -794,11 +803,11 @@ def make_tarballs(repo_path, example_to_file_names, example_to_CMake, ref_mtime)
# Create the Tarballs directory in the source tree if not present
# If it does not exist, assume the tarball repo has not been cloned
# and we need to ignore tar files
tar_dir = make_path(repo_path, 'Tarballs')
tar_dir = make_path(web_repo_dir, 'Tarballs')
if not os.path.exists(tar_dir):
os.makedirs(tar_dir)
with open(make_path(tar_dir, '.gitignore'), 'w') as ofh:
ofh.write('*,tar\n')
# with open(make_path(tar_dir, '.gitignore'), 'w') as ofh:
# ofh.write('*,tar\n')
# Create tarballs
# For each example page, create a directory and copy that example's files
......@@ -840,7 +849,7 @@ def make_tarballs(repo_path, example_to_file_names, example_to_CMake, ref_mtime)
# Now create the tar file for the example
# The tarballs are stored in the source tree
tar = tarfile.open(make_path(repo_path, 'Tarballs', example + '.tar'), 'w')
tar = tarfile.open(make_path(web_repo_dir, 'Tarballs', example + '.tar'), 'w')
tar.add(src_dir, arcname=example)
tar.close()
......@@ -889,31 +898,39 @@ def main():
stats['thumb_count'] = 0
stats['doxy_count'] = 0
repo_dir, doc_dir, repo_url, vtk_src_dir = get_program_parameters()
# repo_dir, web_path, web_url, vtk_src_dir = get_program_parameters()
# The URL corresponding to the source files repository.
# src_url = 'https://gitlab.kitware.com/vtk/vtk-examples'
repo_dir, site_url, web_site_url, web_repo_url, web_repo_dir, vtk_src_dir = get_program_parameters()
print('Paths and folders to use:')
print(repo_dir)
print(site_url)
print(web_site_url)
print(web_repo_url)
print(web_repo_dir)
print(vtk_src_dir)
print()
sub_str = './'
if repo_dir.startswith(sub_str):
repo_dir = re.sub(sub_str, '', repo_dir)
if doc_dir.startswith(sub_str):
doc_dir = re.sub(sub_str, '', doc_dir)
# Find the root path, this program resides in the Admin folder so go up two levels.
root_path = os.path.dirname(os.path.abspath(__file__))
for i in range(2):
root_path = os.path.dirname(root_path)
# The name of the repository on the server.
repo_name = list(filter(None, repo_url.split('/')))[-1]
repo_name = list(filter(None, web_repo_url.split('/')))[-1]
# The user name for the repository.
user_name = list(filter(None, repo_url.split('/')))[-2]
user_name = list(filter(None, web_repo_url.split('/')))[-2]
repo_path = make_path(root_path, repo_dir)
doc_path = make_path(root_path, doc_dir)
doc_path = make_path(web_repo_dir, 'docs')
# Make sure the wiki docs folder exists
if not os.path.exists(doc_path):
os.makedirs(doc_path)
# The cache
cache_path = make_path(repo_path, 'Cache')
cache_path = make_path(web_repo_dir, 'src/Cache')
if not os.path.exists(cache_path):
os.makedirs(cache_path)
......@@ -923,8 +940,8 @@ def main():
vtk_modules_cache_path = make_path(cache_path, 'VTKModules.cache')
vtk_modules_dict = load_vtk_modules_cache(vtk_modules_cache_path)
# Baseline top level path relative to src
baseline_src_path = 'Testing/Baseline'
# Baseline images path (assumed to exist)
baseline_src_path = make_path(web_repo_dir, 'src/Testing/Baseline/')
# Make the reference mtime to be the most recent of the two CMakeLists templates
ref_stat1 = os.stat(make_path(repo_path, 'Admin/VTKQtCMakeLists'))
......@@ -956,7 +973,7 @@ def main():
pages = ['Cxx.md', 'Python.md', 'CSharp.md', 'Java.md', 'JavaScript.md', 'Cxx/Snippets.md', 'Python/Snippets.md',
'Java/Snippets.md', 'VTKBookFigures.md', 'VTKFileFormats.md']
for p in pages:
add_thumbnails_and_links(repo_url, root_path, repo_dir, doc_dir, baseline_src_path, test_images_dict, p, p,
add_thumbnails_and_links(web_repo_url, root_path, repo_dir, doc_path, baseline_src_path, test_images_dict, p, p,
stats)
# C++ Snippets
......@@ -999,8 +1016,8 @@ def main():
dest = make_path(doc_path, k, 'Coverage')
if not os.path.exists(dest):
os.makedirs(dest)
shutil.copy(make_path(repo_path, 'Coverage', k + 'VTKClassesNotUsed.md'), dest)
src = make_path(repo_path, 'Coverage', k + 'VTKClassesUsed.md')
shutil.copy(make_path(web_repo_dir, 'src/Coverage', k + 'VTKClassesNotUsed.md'), dest)
src = make_path(web_repo_dir, 'src/Coverage', k + 'VTKClassesUsed.md')
with open(src, 'r') as ifh:
lines = ifh.readlines()
dest = make_path(doc_path, k, 'Coverage', k + 'VTKClassesUsed.md')
......@@ -1015,9 +1032,9 @@ def main():
if not os.path.exists(dest):
os.makedirs(dest)
instruction_files = ['ForUsers.md', 'ForDevelopers.md', 'ForAdministrators.md', 'Guidelines.md',
'ConvertingFiguresToExamples.md']
'ConvertingFiguresToExamples.md', 'WebSiteMaintenance.md']
for f in instruction_files:
make_instruction_pages(repo_url, root_path, repo_name, user_name, repo_dir, doc_dir, f, f)
make_instruction_pages(web_repo_url, web_site_url, site_url, root_path, repo_dir, doc_path, f, f)
# Copy VTKBook files
if not os.path.exists(make_path(doc_path, 'VTKBook')):
......@@ -1092,7 +1109,7 @@ def main():
continue
# Make the markdown page for each example
make_markdown_example_page(f, lang, lang_ext, root, available_languages, repo_path, doc_path,
kit_name, repo_name, repo_url, user_name, vtk_modules_dict, vtk_src_dir,
kit_name, repo_name, web_repo_url, user_name, vtk_modules_dict, vtk_src_dir,
example_to_file_names, example_to_CMake, code_to_page, stats)
# Generate an html page that links each example code file to its Wiki Example page
......@@ -1101,13 +1118,13 @@ def main():
index_file.write('\n')
sorted_by_code = sorted(code_to_page.items())
for item in sorted_by_code:
index_file.write("<A HREF=" + repo_url + "/wikis" + re.sub(" ", "_", item[1]) + ">" + item[0] + "</A>")
index_file.write("<A HREF=" + web_repo_url + "/wikis" + re.sub(" ", "_", item[1]) + ">" + item[0] + "</A>")
index_file.write(
"<A HREF=" + repo_url + "/blob/master" + re.sub(" ", "_", item[1]) + ".md" + ">" + "(md)" + "</A>")
"<A HREF=" + web_repo_url + "/blob/master" + re.sub(" ", "_", item[1]) + ".md" + ">" + "(md)" + "</A>")
index_file.write("<br>\n")
# Create tarballs for each example
make_tarballs(repo_path, example_to_file_names, example_to_CMake, ref_mtime)
make_tarballs(repo_path, web_repo_dir, example_to_file_names, example_to_CMake, ref_mtime)
# Update the test image cache file if necessary
if stats['test_image_misses'] > 0:
......
......@@ -29,7 +29,7 @@ endif ()
###Download and Build XXX
Click [here to download XXX](https://github.com/ajpmaclean/VTKEx/raw/master/src/Tarballs/XXX.tar) and its *CMakeLists.txt* file.
Click [here to download XXX](WWW/raw/master/Tarballs/XXX.tar) and its *CMakeLists.txt* file.
Once the *tarball XXX.tar* has been downloaded and extracted,
```
cd XXX/build
......
#!/usr/bin/env python
# -*- coding: utf-8 -*-
from __future__ import print_function
import os
import re
try:
from urllib.request import urlopen
except ImportError:
# urllib.request does not exist in Python 2.7
from urllib2 import urlopen
from collections import defaultdict
from urllib.request import urlopen
def get_program_parameters():
......@@ -24,7 +17,7 @@ Typical usage:
To produce tables of classes used and those not used in some_path/VTKExamples/src:
VTKClassesUsedInExamples.py some_path/VTKExamples/src -u
The markdown tables are written to some_path/VTKExamples/src/Coverage
The markdown tables are written to some_path/src/Coverage
Note:
To add links to the VTK class documentation on the web, just add -a as a parameter.
......@@ -33,6 +26,8 @@ Typical usage:
parser = argparse.ArgumentParser(description=description, epilog=epilogue,
formatter_class=argparse.RawTextHelpFormatter)
parser.add_argument('vtk_examples', help='The path to the VTK example source files.')
parser.add_argument('coverage_dest',
help='The path to the folder to store the coverage files. Usually web_dir/src/Coverage')
parser.add_argument('-c', '--columns',
help='Specify the number of columns for unused VTK classes output, default is 5.', nargs='?',
const=5, type=int, default=5)
......@@ -45,7 +40,8 @@ Typical usage:
parser.add_argument('-a', '--add_vtk_html', help='Add html paths to the VTK classes.', action='store_true')
args = parser.parse_args()
return args.vtk_examples, args.columns, args.excluded_columns, args.unused_vtk, args.add_vtk_html
return args.vtk_examples, args.coverage_dest, args.columns, args.excluded_columns,\
args.unused_vtk, args.add_vtk_html
def print_table(table, filename):
......@@ -97,9 +93,10 @@ class VTKClassesInExamples(object):
Determine what classes are being used or not used in the examples.
"""
def __init__(self, base_directory, columns, excluded_columns, unused_vtk, add_vtk_html):
def __init__(self, base_directory, output_directory, columns, excluded_columns, unused_vtk, add_vtk_html):
"""
:param base_directory: The path to the VTK Examples sources, usually some_path/VTKExamples/src
:param output_directory: Where the coverage file will be written.
:param columns: When generating the classes not used table, the number of columns to use.
:param excluded_columns: When generating the excluded classes table, the number of columns to use.
:param unused_vtk: True if the unused VTK class tables are to be generated.
......@@ -115,6 +112,7 @@ class VTKClassesInExamples(object):
self.vtk_html_fmt = '[{:s}](http://www.vtk.org/doc/nightly/html/{:s}#details)'
self.base_directory = base_directory
self.output_directory = output_directory
self.columns = columns
self.excluded_columns = excluded_columns
self.unused_vtk = unused_vtk
......@@ -383,18 +381,21 @@ class VTKClassesInExamples(object):
raise RuntimeError('The classes used tables have not been built.')
if self.unused_vtk and not self.not_used_tables_built:
raise RuntimeError('The classes not used tables have not been built. Enable -u.')
pth = os.path.join(self.base_directory, 'Coverage')
if not os.path.exists(self.output_directory):
os.makedirs(self.output_directory)
for eg in self.example_types:
fn = os.path.join(pth, eg + 'VTKClassesUsed')
print_table(self.classes_used_table[eg], fn)
if self.unused_vtk:
fn = os.path.join(pth, eg + 'VTKClassesNotUsed')
fn = os.path.join(self.output_directory, eg + 'VTKClassesNotUsed')
print_table(self.classes_not_used_table[eg], fn)
else:
fn = os.path.join(self.output_directory, eg + 'VTKClassesUsed')
print_table(self.classes_used_table[eg], fn)
def main():
example_source, columns, excluded_columns, unused_vtk, add_vtk_html = get_program_parameters()
vtk_classes = VTKClassesInExamples(example_source, columns, excluded_columns, unused_vtk, add_vtk_html)
example_source, coverage_dest, columns, excluded_columns, unused_vtk, add_vtk_html = get_program_parameters()
vtk_classes = VTKClassesInExamples(example_source, coverage_dest, columns, excluded_columns, unused_vtk,
add_vtk_html)
vtk_classes.build_tables()
vtk_classes.print_tables()
......
......@@ -67,7 +67,7 @@ endif()
```
###Download and Build XXX
Click [here to download XXX](https://github.com/ajpmaclean/VTKEx/raw/master/src/Tarballs/XXX.tar) and its *CMakeLists.txt* file.
Click [here to download XXX](WWW/raw/master/Tarballs/XXX.tar) and its *CMakeLists.txt* file.
Once the tarball *XXX.tar* has been downloaded and extracted,
```
cd XXX/build
......
## Administrators
Administrators have write access to the [git repository](__REPOSITORY__). If you are a User [go here](../ForUsers) or a Developer [go here](../ForDevelopers).
Administrators have write access to the [VTK Examples Source](__SITE_REPOSITORY__) and to the [VTK Examples Web Source](__WEB_REPOSITORY__). If you are a User [go here](../ForUsers) or a Developer [go here](../ForDevelopers).
## Organization of the Repository
## Organization of the Repositories
The files are stored in a [git repository](__REPOSITORY__) hosted at [github.com](http://www.github.com/). The repository contains several types of files.
The source files for the examples and other files are stored in [VTK Examples Source](__SITE_REPOSITORY__). The web files are stored in a separate repository [VTK Examples Web Source](__WEB_REPOSITORY__).
All example source code, descriptions, test data, and test baselines are stored in the *src/* tree.
### Source Repository
The repository contains several types of files.
## Repository
All example source code, descriptions, test data, and test baselines are stored in the *src/* tree.
The major elements of the tree are:
......@@ -21,20 +23,15 @@ The major elements of the tree are:
|-- src # all of the content to create site/
|-- SyncSiteWithRepo.sh # master script to update site/
|-- Admin
| |-- ScrapeRepo.py # script to create docs/
| |-- ScrapeRepo.py # script to create docs/ in the web site folder
| |-- VTKCMakeLists # template for Cxx examples
| |-- VTKQtCMakeLists # template for Cxx Qt
| |-- sitemap.xml # generated sitemap
| |-- sitemapGenerator.sh # site map generator
|-- Artifacts # Additional images, docs, etc.
|-- Cache # Stores cache files used by ScrapeRepo.py.
|-- Coverage # Stores VTK classes used and classes used by language.
|-- Images # Images used in creating the static web pages.
|-- 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
......@@ -44,34 +41,49 @@ The major elements of the tree are:
|-- VTKBookLaTeX # LaTex version of the VTK Book
|-- stylesheets
|-- extra.css # mkdocs search config
|-- site # static web pages generated by mkdocs
```
### Web Repository
This repository is separate from the vtk examples source files. It contains the generated web pages and other needed files that are copied across from the source repository.
``` bash
|--
|-- site
|-- src # needed content for site generation and site/ operation
|-- Artifacts # Additional images, docs, etc.
|-- Cache # Stores cache files used by ScrapeRepo.py.
|-- Coverage # Stores VTK classes used and classes used by language.
|-- Images # Images used in creating the static web pages.
|-- Testing
| |-- Baseline # Baselines for examples
| | |-- LANGUAGE
| | | |-- TOPIC
| |-- Data # Data for examples
|-- Tarballs # Tar files for each Cxx example
```
## Look and Feel
A priority in moving from the wiki media [VTK Wiki Examples](http://www.vtk.org/Wiki/VTK/Examples) to the Github pages [VTK Examples](__REPOSITORY__/site/) was to provide a modern, familiar look and feel. We also wanted to support tablet and mobile platforms. We chose [MkDocs](http://www.mkdocs.org/) because it generated static HTML pages that can be hosted anywhere.
<img style="border:2px solid beige;float:center" src="__BLOB__/src/Artifacts/OldVersusNew.png?raw=true" />
<img style="border:2px solid beige;float:center" src="__WEB_BLOB__/src/Artifacts/OldVersusNew.png?raw=true" />
### [MkDocs](http://www.mkdocs.org/)
#### Installing MkDocs
MkDocs is a python package and can be installed using `pip`;
```bash
pip install mkdocs
```
MkDocs is a python package and can be installed using `conda` or `pip`.
#### Configuring MkDocs
The *mkdocs.yml* file contains the configuration parameters
The *mkdocs.yml* file contains the configuration parameters:
```bash
site_name: __REPO_NAME__
site_url: https://__USER_NAME__.github.io/__REPO_NAME__/site/
repo_name: __USER_NAME__/__REPO_NAME__
repo_url: __REPOSITORY__
site_name: __WEB_REPO_NAME__
site_url: __WEB_SITE_URL__
repo_name: __WEB_USER_NAME__/__WEB_REPO_NAME__
repo_url: __WEB_REPOSITORY__
theme:
name: material
......@@ -158,7 +170,7 @@ The Materials theme is built using Google's [Material Design](https://material.i
#### Configuring Materials
The materials theme is selected using the *material* keyword in the *mkdocs.yml* file.
The materials theme is selected in the *theme* section of the *mkdocs.yml* file.
## [Google Analytics](https://analytics.google.com/)
......@@ -200,7 +212,7 @@ The code is added to [custom_theme/main.html](__BLOB__/custom_theme/main.html).
### Implementing GCSE
The search box is added to the web pages by adding the gcse search box html
The search box is added to the web pages by adding the gcse search box html to [custom_theme/partials/search.html](__BLOB__/custom_theme/partials/search.html).
``` html
<gcse:searchbox-only>Search</gcse:searchbox-only>
......@@ -210,35 +222,41 @@ The search box is added to the web pages by adding the gcse search box html
### [Lazy Image Loading](https://davidwalsh.name/lazyload-image-fade)
The first implementation had problems loading the [Cxx summary](__REPOSITORY__/site/Cxx/). 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 first implementation had problems loading the [Cxx summary](__WEB_SITE_URL__/Cxx). 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 Lazy Image Loading is implemented in javascript. The javascript is stored in *custom_theme/main.html*. It uses a clever *trick*. Images that should be lazy loaded use a *<img>* tag with a *class=lazy* and attribute *data_src*. If the image is in the viewport, the *data_src* is removed, and the image renders.
### Tiny URLs
The web pages have many URL's that link to images and VTK doxygen pages. The long length of these URLs can increase page load times, especially on the language summary pages.
The web pages have many URL's that link to images and VTK doxygen pages. The long length of these URLs can increase page load times, especially on the language summary pages.
[http://tinyurl.com](http://tinyurl.com) provides a service to map the long URL's into shorted URLs. To speed up the process, we cache the long/short URLs in a file [src/Cache/TestImages.cache](__REPOSITORY__/raw/master/src/Cache/TestImages.cache). *ScrapeRepo.py* uses this cache to only convert URLs that are not in the cache. *ScrapeRepo.py* updates the cache after each run.
[http://tinyurl.com](http://tinyurl.com) provides a service to map the long URL's into shorted URLs. To speed up the process, we cache the long/short URLs in a file `src/Cache/TestImages.cache` in the local checkout of the web repository. *ScrapeRepo.py* uses this cache to only convert URLs that are not in the cache. *ScrapeRepo.py* updates the cache after each run.
### 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](https://htmlmin.readthedocs.io/en/latest/) to compress the generated HTML. The compressed pages are about 30% smaller after running *htmlmin*. We use the command line to process each *index.html* file in *site/*.
*mkdocs* generates HTML pages from the markdown files in `doc` in the local checkout of the web repository. These pages have lots of white space. We use the python package [htmlmin](https://htmlmin.readthedocs.io/en/latest/) to compress the generated HTML. The compressed pages are about 30% smaller after running *htmlmin*. We use the command line to process each `site` in the local checkout of the web repository.
*htmlmin* must be installed:
```bash
pip install htmlmin
```
*htmlmin* must be installed and can be installed using `conda` or `pip`
## Administrator Tasks
They are
- Vet new submissions making sure the guidelines are followed.
- Merge and ...
- Update web pages after new submissions by running `src/SyncSiteWithRepo/py` in the .