-
Notifications
You must be signed in to change notification settings - Fork 200
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Generate and upload documentation page on every build #58
Comments
Not a technical comment, but wouldn't it be nice to host the docs on IPFS instead (considering what kind of project this is)? |
That sounds like a great idea! We can just link to it in the readme over the IPFS.io gateway.
|
I'll take care of getting offline docs generation going. Doing it automatically on merge will be another task, |
Alright, sounds great. Thanks so much for working on this. |
How are you planning to generate the offline docs? We've had a request On 08/16/2016 12:51 PM, Alexander Schlarb wrote:
|
Based on your previous comments I think you might be a bit confused about what Unlike most other programming languages python has the ability to retrieve/display documentation for runtime objects (functions/classes/…) while your running the program (so that you don't need a separate docviewer or browser application open to read the help). >>> import json
>>> help(json.dump) which will display the inline help shipped as part of the The def some_funcy_func():
"""
Hi I'm some piece of useless documentation!
"""
… This would result in the What is left to do is to extract these docstrings and render a web page off of the them (since using ––– I was planning on using the Sphinx documentation suite, that is also used by python itself to generate some nice looking HTML. The only serious drawback about |
Thanks for the in-depth explanation. I didn't understand the mechanics of pydoc at that level, so I've learned something today. I think I phrased my question badly. I wanted to know whether you were going to be updating the source code documentation to conform to some doc style other than what it uses now. I had assumed that pydoc was more structured than the current pep257 documentation style. So you're working on getting Sphinx set up and not altering the existing inline docs?
|
First I'll set up Sphinx. Once that is working, I'll try to convert everything to Sphinx's Napoleon style docstrings (which, unlike RST is actually readable when viewed through pydoc). |
@Alexander255 "The only serious drawback about Sphinx is that it insists on RST (which IMHO is a nightmare), but I've figured out how to (mostly) work around that unfortunate fact." ReStructuredText (ReST), while older, is very similar to markdown but has the advantage that it is strictly defined (unlike markdown which is a horrible collection of incompatible implementations of a not well defined mess pushed forward by Gruber ) and is extensible (the '..' stuff that probably is the part that confuses people). Rant aside, please have a look at the intro at http://www.sphinx-doc.org/en/stable/rest.html to get a really good introduction to ReST. |
@Alexander255 Sounds awesome; thank you so much! My level of care about the documentation style is about 3/10. All I want is something that humans can read that doesn't force you to type redundant information. PEP-257 drove me crazy because it had you summarize each method in a class twice (once at the method level and once at the class level). Anything less verbose than that would be fantastic, whether that's RST or Napoleon. |
Hence the CommonMark initiative (and yes Gruber has not been very helpful at all). I'm aware that ReST isn't that horrible for writing continuous blocks of text (i.e.: the non-API-doc part), but I just prefer MarkDown even for that (using the @whereswaldon Sphinx is very smart about redundant information most of the time so this shouldn't be a problem. |
Current progress: fs:/ipns/QmZ86ow1byeyhNRJEatWxGPJKcnQKG7s51MtbHdxxUddTH/Software/Python/ipfsapi/ |
I'll keep this open as this issue is more about the actual hosting discussed #63, than about the API docs that were recently added. |
Necro post - raising the dead Since #63 is complete, and we have a script at Public values
Secrets
Travis has a means to configure secrets on a repo-wide or per-branch basis: https://docs.travis-ci.com/user/environment-variables/#Encrypting-environment-variables Updating the IPNS link on every pull request build doesn't make sense (it's intended to match the master branch) but it could publish an IPFS hash on every build. Not sure how useful that is (other than validating that it's possible and works correctly). If there were a push-button or automated way to trigger a travis-ci run when It looks like travis does support a master-only build step: https://forum.gitlab.com/t/run-job-in-ci-pipeline-only-on-merge-branch-into-the-master-and-get-merged-branch-name/24195 |
Weeeeeeell, the docs kinda lie on how the documentation is actually deployed. I have used ipfs-cluster for this for years and I think that could probably we run as part of Travis CI (or any other CI/CD solution). I also have the server running already (https://ninetailed.ninja/ is an IPFS website). Setting that stuff up is non-trivial though and I never considered it worth my time, so here we are… |
From #26
The text was updated successfully, but these errors were encountered: