A July 2020 VTK Hackathon

Announcements
24

Tips/tricks and processes

Site migration

Migration of the site to a new repository “should” be straightforward. My personal preference is to use Kitware GitLab.

Once migration happens:

  • Appoint several administrators (I’ll talk about their role later). In the “Year of the Rona” this is even more important. Any one of us could get the Rona and be out of action for a while, or, even worse, kark it. :worried:

  • Verify the site can be built. You can check the links in the local site folder before pushing. You will need to edit:

    mkdocs.yml : Modify site names, username etc.

    src/SyncSiteWithRepo.sh : Run with the new repository name and the local VTK folder.

    src/Admin/ScrapeRepo.py : Line 757 in the function: make_instruction_pages(…) would need to be modified for GitLab.

    src/Instructions : Some of the text will need to be updated. In these files note the use of special strings such as __REPOSITORY__, these are replaced by the appropriate string when src/admin/ScrapeRepo.py is run. See make_instruction_pages(...) in this script.

Once this is done the site will be operational.

Note: The site does use git-lfs, the repository is found here. I have a lot of trouble with it, once again this should be moved to a new site. I think I am the only person now who can update this site. Don’t forget to edit .lfsconfig once this is done.

Administrators

Based on experience, I recommend administrators check out the master. Their role is mainly to:

  • Vet new submissions making sure the guidelines are followed. The developer instructions must be pretty good as there is usually not much to do.
  • Merge and …
  • Update web pages after new submissions by running src/Admin/ScrapeRepo.py.

Some future things to do here:

  • It would be nice to have regular testing of the examples.
  • Python examples are not tested yet. I’m not sure how to do this and keep a “normal” looking Python file. It is something I have been wanting to do for a long time. Ideas or work on this is welcome.

Developers

Follow instructions here (they may need updating for a new site). Also read the Guidelines.

I think the key things are:

  • Decide what folder to put your code into, corresponding to the language, e.g src/Cxx/Graphs. Do not make sub-folders of these existing folders as they will not be scraped.
  • Update the corresponding language chapter file e.g. src/Cxx.md. You can add new headings in this file or add to the existing ones. Be very careful editing this file - follow the layout!!!
  • Remember to add data files into the appropriate folder, if needed, then update/touch CMakeLists.txt and add a test image after testing.
  • If you decide that an example is no longer useful or obsolete, you can move it into the corresponding Deprecated folder e.g. src/Cxx/Deprecated/. Remember to update the corresponding language chapter file e.g. src/Cxx.md and possibly CMakeLists.txt.

Remember that the left-hand index on the web pages reflects the global structure of the site and the right-hand index reflects the indexing in the page you have open, e.g here the indexing on the right-hand side reflects the headings in src/Cxx.md.