Github docs and publishing to SF

The process described here is the most time consuming of all the documentation classes in MisterHouse. This is an unfortunate result of 1) wanting to provide the documentation locally in the user's installation and 2) wanting to make sure updates are reviewed by the developers to ensure the primary user documentation remains stable. Ideally this documentation would not be updated very often. It might be good to consider moving sections that become a pain to keep updated to other documentation classes (i.e. user wiki pages, dev wiki pages, etc.)

Make the Correction

The MisterHouse user documentation is stored in .pod and .html files in the source tree docs directory. The process to changes to these documentation files is the same as for any other source code change. See [fix me] for a description of how to submit code changes.

Update The Web Site

The web site is currently http://misterhouse.sourceforge.net. This site can only be updated by individuals that have been given specific permissions to update the .html files.

• Update local Git repository

cd { where your MH git clone lives }
git checkout master
git pull origin (or upstream)

• Generate the HTML from .pod where needed

cd docs
../bin/update_docs (ignore the complaint about html_alias_docs)

• Use SCP to copy the files to html.sourceforge.net

scp *.html *.css *.gif lib/*.html \
{yourusername}@web.sourceforge.net:/home/project-web/misterhouse/htdocs

I use windows winscp and drag-n-drop; the above will work on linux or windows with a scp package installed.

Update the Github wiki

TBD

I suspect you can use something similar to push the files to the Github wiki: This is only conceptual but should get the idea across:

Update your local Github source code clone

cd {where your MH git clone lives}
git checkout master
git pull origin (or upstream)

Update your local Github wiki clone

cd {where ever you Github wiki clone lives}
git checkout master
git pull origin (or upstream)

Copy the user docs from the main repo to the Github wiki (suggestion: let's put this in a separate subfolder 'userdocs'?)

cd {where ever you Github wiki clone lives}
cp -r {where your MH git clone lives}\docs\*.pod userdocs

Push the Github wiki files that were copied over from the main repo

git push origin

Note that only the “user” documentation should be maintained in this way. i.e. the documentation that is distributed with MH for local access. Ideally, once it is caught up, that documentation will not change all that often. The current wiki content, other developer how-tos, etc. should not be pulled into this process. Those should (IMO) remain on a wiki of some kind with lots of free reign for the users (i.e. the github wiki as it is now).