graspit-simulator/graspit

better home for documentation

Closed this issue · 3 comments

jvarley commented

Thoughts on moving the following to a new location:
http://www.cs.columbia.edu/~cmatei/graspit/
http://www.cs.columbia.edu/~cmatei/graspit/html-manual/graspit-manual.html

There is a lot of content, and no good process for making changes to these beyond directly emailing Matei.

Two possible solutions:

  1. A a github page
    Many examples at:
    https://github.com/showcases/github-pages-examples
    A specific example:
    https://github.com/facebook/react
    https://facebook.github.io/react/
    Benefits:
  • The source for the page would be kept in its own repo in the graspit-simulator org.
  • The site would be under version control, and PR's could be made to update the site.
  • Github hosts the webpage for us for free.

or

  1. a wiki for this git repo at:
    https://github.com/graspit-simulator/graspit/wiki

Benefits:

  • very simple
  • may be modified by github org members
jacquelinekay commented

A note about documentation: consider putting the steps to reproduce generating the documentation in the top-level README.txt, so that people who clone this repo can get an update version of the docs.

e.g. on Ubuntu Linux 14.04, this sort of worked:

  1. download "hyperlatex.sty" by googling for it
  2. place the .sty file in ~/texmf/tex/latex/commonstuff`
  3. cd <graspit root folder>/doc/hyperlatex/
  4. pdflatex graspit-manual.tex

Though it sounds like you are moving away from this latex-based documentation. Markdown is an easy to learn, portable format, but if you need to port existing documentation that contains equations, formatted matrices, etc. it's not so nice...

Github Pages are a nice solution; we are using them with Jekyll Markdown for ROS 2 design documentation. You get more formatting options than a Github wiki, but at the cost of more complexity. Still simpler than messing around with Rails :)

jvarley commented

done.