SimFactory user-guide should be available and updated automatically

Create issue
Issue #502 open
Ian Hinder created an issue

SimFactory has an incomplete user guide in the doc/userguide directory. This is developed using Sphinx, which is a Python framework for writing documentation. You need to install sphinx to generate this documentation. This can be done using something similar to the following:

export PYTHONPATH=/home/ianhin/software/python export PATH=/home/ianhin/software/python/:$PATH hash -r easy_install --install-dir ~/software/python sphinx

Then go into the simfactory/doc/userguide directory and type:

./autogen make html

to generate HTML documentation (type just "make" to see the other possible targets like PDF etc).

This should be regenerated on any commit to the SimFactory/doc/userguide directory and copied to a web-accessible location for inclusion on simfactory.org.

Keyword:

Comments (6)

  1. Ian Hinder reporter
    • removed comment

    The user guide is now built on numrel07 triggered by commits to relevant simfactory subdirectories, and the generated files are then automatically committed to the simfactory.org SVN repository so that they appear under http://simfactory.org/info/documentation/. This is still handled by a procmail recipe attached to my email account. It would be good for this to be a proper SVN commit hook managed at CCT. The script to update the documentation is attached.

  2. Frank Löffler
    • changed status to resolved
    • removed comment

    I believe this is now way out of date and now obsolete. If not, please reopen and accept.

  3. Ian Hinder reporter
    • changed status to open
    • removed comment

    There hasn't been any more development on simfactory than on the user guide, so the user guide is about as good as it ever was. The system for updating it has definitely rotted though. With bitbucket pipelines, we can probably generate the user guide automatically within bitbucket. I don't know how to get it onto simfactory.org, but we could probably get it onto simfactory.bitbucket.io and link to it from simfactory.org.

    I think it would be good to have this available, so I am reopening the ticket.

  4. Ian Hinder reporter
    • removed comment

    The user guide is now automatically updated on each commit and deployed to https://simfactory.bitbucket.io/simfactory2/userguide/.

    This page could be linked to from simfactory.org. I tried to change the link, but I cannot commit to the https://svn.cct.lsu.edu/repos/numrel/simfactory2/www repository (email sent to Steve and Frank with details).

    The bitbucket pipeline is at https://bitbucket.org/simfactory/simfactory2/src/master/bitbucket-pipelines.yml.

  5. Log in to comment