write tutorial in documentation

tulip-control / polytope

Geometric operations on polytopes of any dimension

https://pypi.org/project/polytope

Other

74 stars 19 forks source link

write tutorial in documentation #5

Closed johnyf closed 6 years ago

johnyf commented 10 years ago

Currently there is no documentation at all, which would have been useful also in tulip.

slivingston commented 10 years ago

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.

murrayrm commented 10 years ago

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.

johnyf commented 10 years ago

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

johnyf commented 10 years ago

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

slivingston commented 10 years ago

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

johnyf commented 6 years ago

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.

slivingston commented 6 years ago

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/).

johnyf commented 6 years ago

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

slivingston commented 6 years ago

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.

slivingston commented 6 years ago

@johnyf I commented on one of the commits: https://github.com/tulip-control/polytope/commit/462f817af1782d8a23e83e8aea7d3f2f6e663ebb#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.

johnyf commented 6 years ago

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.

johnyf commented 6 years ago

Addressed by 77b6436946a7a4585222df7dcc351ead704f8e39 and b8a1e9ff243e7a057a48bd7d1cc97ae560fb33c2.