Move documentation to repo
Issue #7
resolved
Currently the documentation for the python-itoolkit is located here. It should be moved to this repo so it is 1) more tightly coupled with the actual code, and 2) change tracking is in place.
Do IBM'ers agree? @rangercairns @ThePrez @kadler
Note, this is what we're doing for the Node.js db connector documentation.
I will seek out community volunteers to accomplish task if IBM'ers give thumbs up.
Comments (11)
-
-
I agree as well.
-
Account Deleted
I think no.
The documentation is already in project (see python-itoolkit / itoolkit / doc). In fact, documentation is generated mutiple 'formats' from comments in the code by make_doc.py (see source).
What 'additional' format did you want??? Can you add to make_doc.py on own???
-
reporter
My bad. I didn't know the doc directory existed. I think the only thing I'd do is make more use of Markdown (add headings, put code in blocks, etc).
Thoughts on removing the contents on the YiPs site and pointing the YiPs page to https://bitbucket.org/litmis/python-itoolkit/src/master/itoolkit/doc ?
-
Account Deleted
Thoughts on removing the contents on the YiPs site and pointing the YiPs page to project (here).
Mmm ... information philosophy, aka, where you get your 'fake news'???
Yips is really big ... really big ... would take a mountain of effort to remove all content and store all the information individual projects. Frankly, i think time is better spent doing things like litmis/db2sock coding ... among many other more interesting Open Source activities.
As geek, with all geek privileges bestowed ...
I declare 'documentation', and/or, copies of documentation, artefacts of user enlightenment war. More merrier. I further declare herding content on the web a mission for a fellow named Don Quixote.
Clear?
-
reporter
My bad (again), I didn't explain well. I don't want to transition all YiPs content and instead only the content that doesn't have a home in a specific repo. That's big picture, let me get to the little picture of this Issue.
I am only proposing to have the Python iToolkit documentation be removed from this YiPs page so we have a single authoritative place to obtain docs (this repo).
Basically delete everything after/including "Interesting learning example with QTEMP." and replace it with a link to the docs in this repo.
I can take care of this so you can focus on db2sock. I just wanted to ask permission vs. forgiveness :-)
-
One thing I'd say is that Python has very good documentation generation that you can leverage from the code. I think having the doc in the code helps keep things in-line with reality. I don't know how well that would work with BitBucket though. Do they have something like GitHub Pages? Having a wiki in the project repo would be good for extra examples and things, though.
-
reporter
I don't know how well that would work with BitBucket though. Do they have something like GitHub Pages?
Yes, they do.
I've created one for the Litmis projects here: https://litmis.bitbucket.io
That page then can link to sub-Litmis projects: https://litmis.bitbucket.io/python-itoolkit/
The subdomain has to be the account/team name, in this case "litmis". I tried creating "python-itoolkit.bitbucket.io" but it didn't work.
Idea: We could use bitbucket webhooks to automatically regenerate docs into the above repo.
Thoughts?
-
reporter
Ok, I've worked up another option.
I now have litmis.bitbucket.io/python-itoolkit dynamically loading the contents of https://bitbucket.org/litmis/python-itoolkit/raw/master/itoolkit/doc/README using the below code.
<html> <script src="https://code.jquery.com/jquery-3.2.1.min.js" integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4=" crossorigin="anonymous"></script> <body> <link rel="import" href="https://bitbucket.org/litmis/python-itoolkit/raw/master/itoolkit/doc/README"> <script> $( document ).ready(function() { var c = document.querySelector('link[rel="import"]').import.querySelector('body').innerHTML; $("#testLoad").html('<pre>' + c + '</pre>'); }); </script> <div id="testLoad">asdfasdf</div> </body> </html>This means we could keep the docs in the python-itoolkit repo, yet have them automatically rendered on litmis.bitbucket.io/python-itoolkit for Google search purposes. The internet tells me Google will index dynamic pages so we'll have to see if that is true.
-
I set up a project at readthedocs.io: http://python-itoolkit.readthedocs.io/en/latest/. It gets rebuilt on each push to the repo. Currently it's set up at my fork, but I'll point it here once pull request #1 is merged.
-
- changed status to resolved
merged the PR and changed the web hook, so things should be good at readthedocs.io. Perhaps you could just redirect there from the bitbucket.io page? We still need to migrate more documentation and adjust the pydoc to use restructuredtext. I'll open a new issue for that to make things more clear for others to make doc updates.
- Log in to comment
@ThePrez agrees