Closed Bug 975476 Opened 11 years ago Closed 11 years ago

Port python-nss API docs to readthedocs.org

Categories

(www.mozilla.org :: Legacy PHP system, defect)

Product:
www.mozilla.org
Component:
Legacy PHP system
Version:
Production
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED FIXED

People

(Reporter: sgarrity, Unassigned)

References

(
URL
)

Details

(Whiteboard: [kb=1293108] )

Attachments

(2 files)

https://github.com/mozilla/bedrock/pull/2335
44 bytes, text/x-github-pull-request
Details | Review
bug-975476-remove-nss-docs.diff
2.44 MB, patch
pmac
: review+
Details | Diff | Splinter Review
Over in Bug 866190, the python-nss pages are being ported from mozilla.org to more appropriate locations. A large chunk of those pages are the python-nss API docs: https://www.mozilla.org/projects/security/pki/python-nss/doc/api/current/html/ We're going to investigate the feasibility of porting those docs to the https://readthedocs.org/ platform.
Blocks: 866190, 956736
Whiteboard: [kb=1293108]
From Kathleen: "For now, it'd be fine to make a snapshot of that folder (https://www.mozilla.org/projects/security/pki/python-nss/doc ) and create a redirect to the snapshot/archive. Then if someone ever does fix Bug #975476 they can have the redirect changed to the new location."
Commits pushed to master at https://github.com/mozilla/bedrock https://github.com/mozilla/bedrock/commit/6c2e739df0c40dc1bf9e122c4f7b07f0b3faa9df Redirect to archived Python NSS docs Bug 975476 https://github.com/mozilla/bedrock/commit/12702a40db07d7c80c3fdb184046ced82a5b6588 Merge pull request #2335 from sgarrity/bug-975476-archive-nss-docs Fix bug 975476: Redirect to archived Python NSS docs
Status: NEW → RESOLVED
Closed: 11 years ago
Resolution: --- → FIXED
Here's a patch to remove the python nss docs from SVN. Here's the SVN summary: D projects/security/pki D projects/security/pki/python-nss D projects/security/pki/python-nss/doc D projects/security/pki/python-nss/doc/api D projects/security/pki/python-nss/doc/api/current D projects/security/pki/python-nss/doc/api/current/html D projects/security/pki/python-nss/doc/api/current/html/api-objects.txt D projects/security/pki/python-nss/doc/api/current/html/class-tree.html D projects/security/pki/python-nss/doc/api/current/html/crarr.png D projects/security/pki/python-nss/doc/api/current/html/epydoc.css D projects/security/pki/python-nss/doc/api/current/html/epydoc.js D projects/security/pki/python-nss/doc/api/current/html/frames.html D projects/security/pki/python-nss/doc/api/current/html/help.html D projects/security/pki/python-nss/doc/api/current/html/identifier-index.html D projects/security/pki/python-nss/doc/api/current/html/index.html D projects/security/pki/python-nss/doc/api/current/html/module-tree.html D projects/security/pki/python-nss/doc/api/current/html/nss-module.html D projects/security/pki/python-nss/doc/api/current/html/nss-pysrc.html D projects/security/pki/python-nss/doc/api/current/html/nss.error-module.html D projects/security/pki/python-nss/doc/api/current/html/nss.error.CertVerifyError-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.error.NSPRError-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.io-module.html D projects/security/pki/python-nss/doc/api/current/html/nss.io.AddrInfo-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.io.HostEntry-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.io.NetworkAddress-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.io.Socket-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss-module.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.AVA-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.AlgorithmID-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.AuthKeyID-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.AuthorityInfoAccess-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.AuthorityInfoAccesses-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.BasicConstraints-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CRLDistributionPoint-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CRLDistributionPts-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CertDB-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CertVerifyLog-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CertVerifyLogNode-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.Certificate-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CertificateExtension-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.CertificateRequest-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.DN-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.DSAPublicKey-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.GeneralName-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.InitContext-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.InitParameters-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.KEYPQGParams-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PK11Context-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PK11Slot-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PK11SymKey-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PKCS12DecodeItem-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PKCS12Decoder-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PrivateKey-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.PublicKey-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.RDN-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.RSAGenParams-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.RSAPublicKey-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.SecItem-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.SignedCRL-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.SignedData-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.nss.SubjectPublicKeyInfo-class.html D projects/security/pki/python-nss/doc/api/current/html/nss.ssl-module.html D projects/security/pki/python-nss/doc/api/current/html/nss.ssl.SSLSocket-class.html D projects/security/pki/python-nss/doc/api/current/html/toc-everything.html D projects/security/pki/python-nss/doc/api/current/html/toc-nss-module.html D projects/security/pki/python-nss/doc/api/current/html/toc-nss.error-module.html D projects/security/pki/python-nss/doc/api/current/html/toc-nss.io-module.html D projects/security/pki/python-nss/doc/api/current/html/toc-nss.nss-module.html D projects/security/pki/python-nss/doc/api/current/html/toc-nss.ssl-module.html D projects/security/pki/python-nss/doc/api/current/html/toc.html
Attachment #8506114 - Flags: review?(pmac)
Patch looks good. Reopening bug as this doesn't fix it, just moves elsewhere for now.
Status: RESOLVED → REOPENED
Resolution: FIXED → ---
Attachment #8506114 - Flags: review?(pmac) → review+
FWIW due to the way the python-nss documentation is currently structured (inside docstrings inside CPython code) it's impossible to port to readthedocs.org. readthedocs requires Sphinx compatible reStructuredText, this means pulling all the docstrings out of the CPython code and putting them into someother files(s) with a bunch more metadata. Then the docstrings need to be reworked. In other words it's non-trivial and at the moment it's not scheduled as a work item by the sponsoring company.
Merged the SVN clean up r133212. I think we can close this bug as I don't think it's feasible to port to readthedocs. We could call this a WONTFIX, since that original goal didn't get met, but I think we're ok calling this FIXED as we've found another 'solution'.
Status: REOPENED → RESOLVED
Closed: 11 years ago → 11 years ago
Resolution: --- → FIXED
John, Will these docs need updating at some point? They're in an archive ATM which shouldn't really be updated. If it's just a matter of hosting some HTML somewhere, a github repo using Github Pages works really well. If it will never need updating, then where it is will work fine.
Flags: needinfo?(jdennis)
The docs get updated with each new release which has been averaging about twice a year. I can't think of a reason to need access to prior doc versions so archiving is not an issue. The issue is having the API doc somewhere where folks can access it on a public web site. The tool (epydoc) that generates the doc produces HTML which Mozilla prohibits (some type of cross site scripting issue) so Mozilla won't host the doc in it's current form (although manually fixing the issue is not hard, we just have to make sure it happens each time the doc is generated, perhaps this could be scripted). Early on we thought readthedocs would be a good host but when I tried to move the doc there I discovered readthedocs only accepts doc in Sphinx format, getting the doc in Sphinx format is the task I was referring to in comment #6. So at the moment the doc is orphaned. Even if we fix the epydoc generation I'm not sure Mozilla will host plain HTML, isn't the idea you've now moved to wiki format?
Flags: needinfo?(jdennis)
Pmac and sgarrity: Given the additional info from John in comment #9, could the api doc live on Github? Thx, Jen
We could definitely try a github repo. I'll set it up. John, mozilla.org isn't a wiki, but developer.mozilla.org is (MDN). The docs could live there, but they'd have to be manually updated via the wiki editor. I'll setup a repo for the docs as an experiment. We can use it if we like and link to it, or delete the repo if not.
Here it is: http://mozilla.github.io/python-nss-docs/ If we like this, it'll be easy to update in future by just cloning the repo and submitting a PR for the changes (or let me know your github uername John and I'll make you an owner). Also we can change links and add further redirects to this source.
Flags: needinfo?(jdennis)
Thank you Paul, the doc looks good on github, this seems like the way to go. It's also timely as I'm about to push a new 0.16.0 release in a day or so and that will give me a chance to try out the process. My github username is jdennis. I assume what you did was take the generated HTML files and did a 'git add' on them manually as opposed to some other automated process, correct? Thus when I want to update them I'll clone the existing repo, overlay the new generated files, add any new files, delete any old files, do a commit, and then push. Is that your expectation? We'll also need to update the link to the doc on https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Python_binding_for_NSS
Flags: needinfo?(jdennis)
Great! I've got you setup with access to the repo. And your process is pretty much spot on. I'd recommend the following: 1. Clone the repo 2. Make sure you're on the gh-pages branch (should be the default) 3. Delete all of the files (except README.md) 4. Add the new files. 5. Add all changes via `git add .` 6. Commit said changes. 7. Push new commit to github. Changes should then be live within a minute or two. I'll hop on updating redirects and links on our side and MDN. I'll add info about the above procedure to the README in the repo to make it easier next time.
Commits pushed to master at https://github.com/mozilla/bedrock https://github.com/mozilla/bedrock/commit/ec77af67b423fdd99ffa49bec983e3e429c8b968 Bug 975476: Update redirects for python-nss docs. We now have a github repo setup using github-pages to publish the docs. The developer (@jdennis) has permissions on it, and they will be updated there. I've made the redirect for the docs more specific since after examining the archive it's clear that this directory structure is all that was in there, so there wouldn't be any valid links to any URLs between "python-nss" and "html". I made the trailing slash on the MDN redirect optional since that form of the URL is the one used on the PyPI page for the package and was redirecting to a 404 at the archive. https://github.com/mozilla/bedrock/commit/19d576c228e672121be5509b7a10528f88714aaf Merge pull request #2407 from pmclanahan/update-python-nss-docs-urls-975476 Bug 975476: Update redirects for python-nss docs.
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: