SIMONAPreprocessor
How to modify the documentation

If you have a tutorial or just a small hint you should contribute it to the documentation.
To do this you need a valid Redmine account on intfischer.ka.fzk.de/redmine (not poemuser).
The only tools you need are

  • subversion (this is already installed, if you already got a source tree)
  • doxygen to build the documentation
    IMPORTANT: This needs to be at least Doxygen 1.8.0, Ubuntus version is too old. If you are using Ubuntu, download the latest version from http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc - x86_64 linux for most people - and either unpack the executable into your bin directory or extract the package to a folder of your choice and create a symlink to the executable:
    1 sudo ln -s /path_to_your_doxygen/bin/doxygen /usr/bin/

First of all: All the user documentation for the SIMONA preprocessor resides in the python subfolder of your local copy of SIMONA. To change the documentation as a developer (or documenter ;-), you need to edit some python files where the part of the docu you're working on is located. Then, you need to compile the docu. How you can find these files and compile them is described on an example below.
If you want to have a look on the compiled docu, go to the python/docs/html folder in your SIMONA folder and open the file

1 index.html

Note there most likely will not be any docu until you compiled it yourself.
You can navigate through the docu in a browser (just like you have already done when you are reading this). If you cannot see your changes (and you are sure you saved and compiled them), please check first if you are reading the local version of the docu (should look like file:///PATH_TO_SIMONA/python/docs/html/Docu.html) or the online version. If you see the "old" version in your locally compiled docu, try to delete your browser cache and reload the page.

To give you an impression how all this works, let's assume you found this page hardly understable and want to improve it.

  • First, enter the python subfolder in your SIMONA path (using a console).
  • Now, let's see if you can compile the documentation. You should have installed doxygen and be in the python folder, so run
    1 doxygen ./poempp.doxygen
    It may take a while and you should see a lot of messages that tell you what's going on. When it's finished, have a look on the docu (open it as described above). If some error message appeared while compiling or you can't open the documentation, something is wrong and you ask the maintainers about what to do.
  • If the compiling worked, search in the python folder for a word near to the one you want to edit. As a test search, let's assume you search for "unmodified" to find this page:
    1 grep unmodified *.py
    You will see a list of files and where the string you searched for (unmodified) is found.
    After you found out which file you want to change, open the corresponding file with the editor of your choice, search for the string (here unmodified again) and change what you want. Take a look at what's written around our unmodified string, there you will see how the existing documentation is written and how you have to do your changes to fit in.
  • After you made your changes (do not forget to save them), build the no longer unmodified documentation containing your changes on your machine to see if it works:
    1 doxygen ./poempp.doxygen
    After the process finished, have a look at your local version of the docu to ensure everything went fine and your changes are what and where you want them to be.
  • Finally, if everything is correct, you need to checkin your changes with subversion to ensure everybody gets them.
    Let's assume your changes took place in the file myfile.py. Use
    1 svn diff myfile.py
    and see if there are other changes you do not want to commit. The diffs shows the differences between your local fork of the code tree and the repository on the server.
    Clean up your file until the diff only shows what you want changed (if you changed something for testing or for fun only, make sure not to check it in!). Then enter
    1 svn commit myfile.py -m "Documentation: I changed the explanation of forcefield B"
    Make sure the remark in parentheses is meaningful as it can be seen in the changelogs. After the check-in, your changes are available for everybody.
    1 svn diff myfile.py
    will be empty, because your changes are now included in the repository. It may take a while until your changes appear in the "official" documentation on the server, as it's usually build during the night.

Now, hopefully you know how you can change the documentation. Have fun doing it, feel free to change anything you find misunderstandable or add what you're missing and in doubt, please write a little bit more than less.
Thank you for your help!