Skip to content
Snippets Groups Projects
Commit cae2bce4 authored by Andrew Maclean's avatar Andrew Maclean
Browse files

Fixing links, improving instructions 

Former-commit-id: fc3937e7
parent 465f06cc
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
src/Admin/sitemapGenerator → src/Admin/sitemapGenerator.sh
+ 0
− 0
View file @ cae2bce4
File moved
src/Instructions/ConvertingFiguresToExamples.md
+ 5
− 5
View file @ cae2bce4
......@@ -2,14 +2,14 @@ There is an ongoing effort to convert the examples in the [VTK Book](http://www.
# Process to Convert Figures to Examples
1. Follow the procedure [ForDevelopers](/Instructions/ForDevelopers) to contribute examples.
1. Follow the procedure [ForDevelopers](../ForDevelopers) to contribute examples.
2. Download a copy of the [VTK Book](http://www.kitware.com/products/books/VTKTextbook.pdf).
3. Look at the [VTKBookFigures](/VTKBookFigures) page and look for examples that have not been converted. These examples will not have a link to source code.
4. Go to your VTK source checkout. Run the script [VTKExamples/src/Admin/getDeletedFile.sh](https://github.com/lorensen/VTKExamples/blob/master/src/Admin/getDeletedFile.sh) with the name of the source file (e.g. walkCow.tcl) in the figure example to be converted. This script will create a source file in the current directory and also report the URL for the original repo location of the example.
3. Look at the [VTKBookFigures](../../VTKBookFigures) page and look for examples that have not been converted. These examples will not have a link to source code.
4. Go to your VTK source checkout. Run the script [VTKExamples/src/Admin/getDeletedFile.sh](https://github.com/ajpmaclean/VTKEx/blob/master/src/Admin/getDeletedFile.sh) with the name of the source file (e.g. walkCow.tcl) in the figure example to be converted. This script will create a source file in the current directory and also report the URL for the original repo location of the example.
5. Pick a source directory to contain the new example. Look at the Chapter heading in the book to guide where to put the new example.
6. Convert the source tcl code or old C++ code to C++ code that will compile and run with the current VTK API. Follow the [guidelines for coding C++ examples](/Instructions/Guidelines).
6. Convert the source tcl code or old C++ code to C++ code that will compile and run with the current VTK API. Follow the [guidelines for coding C++ examples](../Guidelines).
7. If the figure example name is short, e.g. bluntStr we suggest giving it a more descriptive name e.g. BluntStreamlines. Notice the first letter is uppercase.
7. Edit the [VTKBookFigures page](/VTKBookFigures) as follows:
7. Edit the [VTKBookFigures page](../../VTKBookFigures) as follows:
1. In the first column of the table, add a link from the Figure to the source code.
2. In the second column of the table, add the VTK classes that are illustrated by the example.
3. In the third column, cut and paste the caption from the VTK Book.
......
src/Instructions/ForAdministrators.md
+ 27
− 22
View file @ cae2bce4
Administrators have write access to the [git repository](https://github.com/ajpmaclean/). If you are a User [go here](/Instructions/ForUsers) or a Developer [go here](/Instructions/ForDevelopers).
Administrators have write access to the [git repository](https://github.com/ajpmaclean/VtkEx). If you are a User [go here](../ForUsers) or a Developer [go here](../ForDevelopers).
# Organization of the Repository
The are stored in a [git repository](https://github.com/ajpmaclean/.git) hosted at [github.com](http://www.github.com/). The repository contains several types of files.
The are stored in a [git repository](https://github.com/ajpmaclean/VtkEx.git) hosted at [github.com](http://www.github.com/). The repository contains several types of files.
All example source code, descriptions, test data, and test baselines are stored in the *src/* tree.
......@@ -19,31 +19,36 @@ The major elements of the tree are:
|-- 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
| |-- ScrapeRepo.py # script to create docs/
| |-- 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
|-- Tarballs # Tar files for each Cxx example
|-- Testing
| |-- Baseline # Baselines for examples
| | |-- LANGUAGE
| | | |-- TOPIC
| |-- Data # Data for examples
|-- VTKBook # Markdown version of the VTK Book
|-- VTKBookLaTeX # LaTex version of the VTK Book
|-- 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](http://www.vtk.org/Wiki/VTK/Examples) to the Github pages [](https://ajpmaclean.github.io//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.
A priority in moving from the wiki media [VTK Wiki Examples](http://www.vtk.org/Wiki/VTK/Examples) to the Github pages [](https://ajpmaclean.github.io/VtkEx/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="https://github.com/ajpmaclean//blob/master/src/Artifacts/OldVersusNew.png?raw=true" />
<img style="border:2px solid beige;float:center" src="https://github.com/ajpmaclean/VTKEx/blob/master/src/Artifacts/OldVersusNew.png?raw=true" />
### [MkDocs](http://www.mkdocs.org/)
#### Installing MkDocs
......@@ -168,7 +173,7 @@ The overall look and feel are established at [https://cse.google.com/cse/](https
```
### Configuring GCSE
The code is added to [custom_theme/main.html](https://github.com/ajpmaclean//blob/master/custom_theme/main.html).
The code is added to [custom_theme/main.html](https://github.com/ajpmaclean/VtkEx/blob/master/custom_theme/main.html).
```html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<gcse:searchbox-only>Search</gcse:searchbox-only>
......@@ -181,7 +186,7 @@ The search box is added to the web pages by adding the gcse search box html
## Performance
### [Lazy Image Loading](https://davidwalsh.name/lazyload-image-fade)
The first implementation had problems loading the [Cxx summary](/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](https://ajpmaclean.github.io/VTKEx/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 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.
......@@ -189,7 +194,7 @@ The Lazy Image Loading is implemented in javascript. The javascript is stored in
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/Admin/TinyUrlCache](https://github.com/ajpmaclean//raw/master/src/Admin/TinyUrlCache). *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](https://github.com/ajpmaclean/VtkEx/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.
### Minify HTML pages
......@@ -201,11 +206,11 @@ pip install htmlmin
```
## Administrator Tasks
### [ScrapeRepo](https://github.com/ajpmaclean//blob/master/src/Admin/ScrapeRepo)
### [ScrapeRepo.py](https://github.com/ajpmaclean/VtkEx/blob/master/src/Admin/ScrapeRepo.py)
<img style="border:2px solid beige;float:center" src="https://github.com/ajpmaclean//blob/master/src/Artifacts/ScrapeRepo.png?raw=true" />
<img style="border:2px solid beige;float:center" src="https://github.com/ajpmaclean/VtkEx/blob/master/src/Artifacts/ScrapeRepo.png?raw=true" />
Given a *RepositoryDir*, *DocDir* and a *RepositoryUrl*, *ScrapeRepo* proceeds as follows:
Given a *SiteDir*, *DocDir*, *RepositoryDir* and a *RepositoryUrl*, *ScrapeRepo* proceeds as follows:
1. Adds thumbnails to the *Cxx.md* and *Python.md* summary pages. A thumbnail is added if a _src/Testing/Baseline/_**LANG**/**TOPIC**/_Test_**EXAMPLE**_.png_ image exists for the example.
......@@ -226,21 +231,21 @@ The *SyncSiteWithRepo.sh* shell script executes all of the steps to update the s
1. Makes sure the site is up
2. Pulls updates from the [master repository](https://github.com/ajpmaclean/).
2. Pulls updates from the [master repository](https://github.com/ajpmaclean/VtkEx).
3. Pulls updates from the [src/Tarballs repository](https://github.com/ajpmaclean/VTKWikiExamplesTarballs)
3. Pulls updates from the [src/Tarballs repository](https://github.com/ajpmaclean/VTKEx/tree/master/src/Tarballs)
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.
The tarballs should be kept in a separate repository to reduce the size of the main repository. They are only accessed from the individual example pages. Currently they are in the main repository.
4. Creates the coverage files
The [src/Admin/VTKClassesUsedInExamples.py](https://github.com/ajpmaclean//blob/master/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.
The [src/Admin/VTKClassesUsedInExamples.py](https://github.com/ajpmaclean/VtkEx/blob/master/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.
4. 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.
5. Runs the [ScrapeRepo script](https://ajpmaclean.github.io//site/Instructions/ForAdministrators/#scraperepo)
5. Runs the [ScrapeRepo script](https://github.com/ajpmaclean/VtkEx/blob/master/src/Admin/ScrapeRepo.py)
populate the *docs* directory.
......@@ -252,7 +257,7 @@ The *SyncSiteWithRepo.sh* shell script executes all of the steps to update the s
8. Copies the sitemap.xml file
This file is updated periodically by [sitemapGenerator](https://github.com/ajpmaclean//blob/master/src/Admin/sitemapGenerator)
This file is updated periodically by [sitemapGenerator](https://github.com/ajpmaclean/VtkEx/blob/master/src/Admin/sitemapGenerator.sh)
9. Minify the HTML
......
src/Instructions/ForDevelopers.md
+ 7
− 7
View file @ cae2bce4
## Introduction
The success of the VTK Examples depends on the contributions from the VTK user community. If you wish to contribute to this valuable resource, please follow these guidelines. If you are a VTK Example User, [go here](../Instructions/ForUsers) or an Example Administrator [go here](../Instructions/ForAdministrators).
The success of the VTK Examples depends on the contributions from the VTK user community. If you wish to contribute to this valuable resource, please follow these guidelines. If you are a VTK Example User, [go here](../ForUsers) or an Example Administrator [go here](../ForAdministrators).
C++, C#, Python, and Java examples are welcome! Examples should illustrate a single concept.
## Follow the Coding Guidelines
When you write an example, please follow the [coding guidelines](../Instructions/Guidelines). Create the example on your local repository, compile and run it before you generate a pull request.
When you write an example, please follow the [coding guidelines](../Guidelines). Create the example on your local repository, compile and run it before you generate a pull request.
Some additional steps need to be done for Python C# and Java, see the sections below.
......@@ -105,9 +105,9 @@ DataStructures, Filters, GeometricObjects, Images, Meshes, etc.
2. Check the:
- [Cxx available snippets](/Cxx/Snippets).
- [Python available snippets](/Cxx/Snippets).
- [Java available snippets](/Cxx/Snippets).
- [Cxx available snippets](../../Cxx/Snippets).
- [Python available snippets](../../Python/Snippets).
- [Java available snippets](../../Java/Snippets).
3. Save your source code in VTKEx/src/**LANGUAGE**/**TOPIC**/
......@@ -158,8 +158,8 @@ Keep the same directory structure as that in Cxx.
The following snippets can be used to write the image out:
- [WriteImage](https://ajpmaclean.github.io/VTKEx/site/Python/Snippets/WriteImage/) for Python
- [WriteImage](https://ajpmaclean.github.io/VTKEx/site/Java/Snippets/WriteImage/) for Java
- [WriteImage](../../Python/Snippets/WriteImage/) for Python
- [WriteImage](../../Java/Snippets/WriteImage/) for Java
- Then follow step 6 above
......
src/Instructions/ForUsers.md
+ 1
− 1
View file @ cae2bce4
If you want to use [VTK Ex](https://github.com/ajpmaclean/VTKEx), you have several options. If you are a VTK Example Developer, [go here](../Instructions/ForDevelopers) or a VTK Example Administrator [go here](../Instructions/ForAdministrators).
If you want to use [VTK Ex](https://github.com/ajpmaclean/VTKEx), you have several options. If you are a VTK Example Developer, [go here](../ForDevelopers) or a VTK Example Administrator [go here](../ForAdministrators).
## Build an example
......
src/Instructions/Guidelines.md
+ 5
− 5
View file @ cae2bce4
......@@ -13,7 +13,7 @@ All examples should follow the VTK programming style and there should be a singl
### C++
* The indentation style can be characterized as the [AllmannStyle](https://en.wikipedia.org/wiki/Indent_style#Allman_style). The curly brace (scope delimiter) is on a separate line and aligns with the control statement, The control block is indented by two spaces (**no tabs**).
* The indentation style can be characterized as the [AllmannStyle](https://en.wikipedia.org/wiki/Indent_style#Allman_style). The curly brace (scope delimiter) is on a separate line and aligns with the control statement, The control block is indented by two spaces (**no tabs**). A suitable `.clang-format` is provided in `src/Cxx` [see here](https://github.com/ajpmaclean/VtkEx/blob/master/src/Cxx/.clang-format).
Example:
......@@ -121,7 +121,7 @@ writer->SetFileName ( argv[3] );
* Always provide a background for the renderers. Avoid setting the background to white.
* Use [vtkNamedColors](http://www.vtk.org/doc/nightly/html/classvtkNamedColors.html) for setting colors of actors and renderer backgrounds. [This html file](http://htmlpreview.github.io/?https://github.com/lorensen/VTKExamples/blob/master/src/Python/Visualization/VTKNamedColorPatches.html) shows the colors that are available.
* Use [vtkNamedColors](http://www.vtk.org/doc/nightly/html/classvtkNamedColors.html) for setting colors of actors and renderer backgrounds. [VTKNamedColorPatches](http://htmlpreview.github.io/?https://github.com/ajpmaclean/VTKEx/blob/master/VTKNamedColorPatches.html) shows the colors that are available. If you are using a color series, then you can choose what you want from here [VTKColorSeriesPatches](http://htmlpreview.github.io/?https://github.com/ajpmaclean/VTKEx/blob/master/VTKColorSeriesPatches.html).
For example,
......@@ -140,7 +140,7 @@ is preferred over
renderer->SetBackground(0.9412, 0.9020, 0.5490);
```
* Use admonitons to warn/cite/info, etc. [Here is a summary of admonitions](https://lorensen.github.io/VTKExamples/site/Instructions/ForAdministrators/#admonition).
* Use admonitions to warn/cite/info, etc. [Here is a summary of admonitions](https://ajpmaclean.github.io/VTKEx/site/Instructions/ForAdministrators/#admonition).
### Python
......@@ -169,12 +169,12 @@ if __name__ == '__main__':
* Input/Output filenames and parameters.
Use this snippet [GetProgramParameters](https://lorensen.github.io/VTKExamples/site/Python/Snippets/GetProgramParameters/)
Use this snippet [GetProgramParameters](https://ajpmaclean.github.io/VTKEx/site/Python/Snippets/GetProgramParameters/)
### Java
In general Python submissions should follow the VTK Programming style and the comments outlined for C++ above (with language appropriate modification).
For Java code layout, look at [CylinderExample](https://lorensen.github.io/VTKExamples/site/Java/GeometricObjects/CylinderExample/)
For Java code layout, look at [CylinderExample](https://ajpmaclean.github.io/VTKEx/site/Java/GeometricObjects/CylinderExample/)
Java code styling follows the usual style as implemented in the IDEs.
......
src/SyncSiteWithRepo.sh
+ 5
− 4
View file @ cae2bce4
#!/bin/bash
#
# SyncSiteWithRepoPy3 - synchronize the examples site with the
# examples repo
# examples repository
#
if [ $# -lt 2 ]
then
......@@ -39,7 +39,8 @@ echo "2) Create coverage files"
echo "3) Scrape the repo"
rm -rf docs/*
rm -rf site/*
src/Admin/ScrapeRepo.py ./src ./docs ${REPO} ${VTK_SOURCE_DIR}
# Assumes src, docs by default for the repo_dir and the doc_dir.
src/Admin/ScrapeRepo.py ${REPO} ${VTK_SOURCE_DIR}
echo "4) Check for a successful scrape"
pushd docs
......@@ -66,8 +67,8 @@ echo "6.1 Modify highlight color to semitransparent Lavender"
(cd site/assets/stylesheets; sed -i -e 's/background-color:rgba(255,235,59,\.5)/background-color:rgba(230,230,250,0.6)/g' application.*.css)
#####################
#echo "Premature exit for testing"
#exit
echo "Premature exit for testing"
exit
#####################
echo "7) Minify Html"
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment