write tutorial in documentation about polytope HOT 12 CLOSED

Where should the release documentation be hosted? Recall that the current location for TuLiP is http://tulip-control.sourceforge.net/doc/. One possibility that could ease the road to package independence is to use http://tulip-control.sourceforge.net/polytope for a while, and then redirect to a long-term location when eventually found.

from polytope.

That path seems fine. Another possibility is http://tulip-control.sf.net/doc/polytope.
We can also set up tulip-control.org/doc/polytope to point to the proper spot.

from polytope.

An alternative place to host the documentation is pythonhosted, the default place for documentation of PyPI packages.

from polytope.

9293989 adds an initial "mini" documentation to accompany the initial release on PyPI.

from polytope.

Though there is now a tutorial, I recommend that we keep this issue open until there is a site hosting polytope documentation. If we decide upon a URL before a hosting location, then we could direct it to https://github.com/tulip-control/polytope/blob/master/doc/tutorial.md

from polytope.

I suggest that we use GitHub pages, which works from a Markdown file, without need for extra steps or dependencies. Branches other than gh-pages are supported, but I think gh-pages is the simplest option with the least effect on branch master. To update the documentation, we can either push new commits, or replace the commit with the old version.

I have pushed the tutorial to gh-pages. The result is at: http://tulip-control.github.io/polytope/. If there is agreement, I think we can close this issue.

from polytope.

• I think that this solution is good, and that the issue #5 can be closed. Perhaps wait at most 1 more day for admonitions.
• A link should be provided from the root README. I recommend to prefer the HTTPS URL: https://tulip-control.github.io/polytope/
• Manually renaming doc/tutorial.md to index.md is a hassle. If you agree, I shall make a script to automate this.
• For the sake of complete instructions about rebuilding stuff, I recommend that an explicit note is included about the documentation release being built with Jekyll via GitHub Pages (https://jekyllrb.com/docs/github-pages/).

from polytope.

I agree with the documentation changes, which have been added on branch doc, and about creating a copying script.

from polytope.

I reviewed your changes on the doc branch, and I added a shell script, doc/build.sh, that automates the release process except for git push. Some users might not find the script useful, but it also serves as documentation for how to manually perform the release.

from polytope.

@johnyf I commented on one of the commits: 462f817#commitcomment-24813889

Deleting or keeping in the comments (as you have) does not seem critical because we plan to eventually audit or freshly write that function.

from polytope.

Given that the line was unused in the past, I will change that commit to delete the line. I will merge the branch doc into master later today.

from polytope.

Addressed by 77b6436 and b8a1e9f.

from polytope.