Website Maintenance
###################

This is a brief guide on how to make changes to this website (last updated by FG, Aug 2023).

Page editing privileges are restricted to one or two persons per group, normally the PI and one postdoc. 
Team members who are currently enabled:

  - Emmanouil Kioupakis <kioup@umich.edu>
  - Roxana Margine <rmargine@binghamton.edu>
  - Samuel Poncé <samuel.ponce@uclouvain.be>
  - Marios Zacharias <Marios.Zacharias@insa-rennes.fr>
  - Sabyasachi Tiwari <sabyasachi.tiwari@austin.utexas.edu>
  - Feliciano Giustino <fgiustino@oden.utexas.edu> 

To add or remove someone, please contact STX or FG.

Pages can be edited via an SVN server hosted by the Oden Institute at UT. To make changes, we need to have a local copy of the repository, and commit changes when ready. The server has a post-commit hook which runs ``make clean html`` at every instance of ``svn commit``, therefore the website will be up-to-date as soon as you issue ``svn commit``.

To start using SVN on your local computer:  

1. Set up SVN locally

   .. code-block:: shell

      sudo apt update
      sudo apt install subversion -y
      sudo apt install sphinx-rtd-theme-common -y
      sudo apt install sphinx-common -y
      sudo apt install python3-sphinx-rtd-theme -y

2. Check out the remote repo

   .. code-block:: shell
      
      svn co https://svn.oden.utexas.edu/repos/cqme/trunk/docs

3. Build the HTML pages

   .. code-block:: shell

      cd docs 
      make clean html

4. Visualize the website locally

   .. code-block:: shell
 
      firefox file://[location of your docs folder]/build/html/index.html

5. Make your changes and verify the result

   - Modify the file(s) you are working on in the folder ``source/doc``
   - Go back to the ``docs`` folder and issue ``make clean html``
   - Reload your web browser


6. Once you are satisfied with your changes, do ``svn commit`` to remote server

   .. code-block:: shell

      svn commit -m "This is my change"

7. If you are planning to make changes, and you already did step 2, then update your local repo to sync with the
   remote server:

   .. code-block:: shell

      svn update

   If you want to automate this process, add the following line to ``/etc/crontab``

   .. code-block:: shell

      00  * * * * cd [location of your docs folder] && svn update

   In this example, your local repo is updated every hour.

**Important Notes** 

  - Only pages with extension ``.rst`` inside the folder ``docs/source/docs`` should be modified.
  - If you need to add images or PDFs etc, please place them in the appropriate subfolders, e.g. ``docs/source/doc/images``.
  - Do not place new files outside of the folder ``doc``.
  - Do not modify the files ``index.rst``, ``DevelopersMeetings.rst``, ``SteeringCommitteeMeetings.rst``, ``WebsiteMaintenance.rst``. FG and SXT will take care of these special files which need encryption at every update.
  - A simple RST cheatsheet can be found `here <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_ 

A reminder of simple SVN commands:

  - ``svn add FILENAME; svn commit -m "Added a new file"``
  - ``svn delete FILENAME; svn commit -m "Removed this file"``
  - ``svn mv OLDFILE NEWFILE; svn commit -m "Changed filename"``