rm doc-generation code that made mostly-unused docs

Review Request #704 — Created July 19, 2014 and submitted

This code worked hard to generate some documentation pages.
The Google analytics numbers point out: these pages were largely unread.
Some (but not all) of this code broke in a refactor: it generated empty docs.
Yet nobody complained.

Rather than work hard to fix and maintain this code, I'm ripping it out.
Behold the fiery debate: https://groups.google.com/forum/#!topic/pants-devel/f7V4_6kLdZs

  • 1
  • 0
  • 0
  • 0
  • 1
Description From Last Updated
First an overall comment that I don't expect you to fix in this review. I think it is weird to ... ZU zundel
  1. I've come across these (beautifully formatted) python docs when searching on pantsbuild and I concur they should probably be removed because they are almost never what I'm looking for when searching the web.
  2. build-support/bin/publish_docs.sh (Diff revision 1)
    First an overall comment that I don't expect you to fix in this review.   I think it is weird to copy stuff from the generated output back into the source.  What I think should be happening is copying files into the dist/ directory and using that as the place to publish from. Then we wouldn't have to worry about a .gitignore file and the staleness issue I'm commenting on next.
    There are some of the old files listed in .gitignore. I guess it doesn't hurt to leave them because we didn't add a step to clean them out of src/python/pants/docs/ and they will stay around until someone manually removes them or does a git clean -fdx
    1. Darned good points. "Fixed" by creating a couple of issues:
      https://github.com/pantsbuild/pants/issues/371 : wait a month. meanwhile, probably everyone will run 'git clean -fdx'. Then we can fix up the .gitignore and few folks will be surprised by these files showing up.
      https://github.com/pantsbuild/pants/issues/370 : yeah, our doc-publish process is silly and wrong
Review request changed

Status: Closed (submitted)