convert and move about 1/2 of our docs from .rst to .md

Review Request #1176 — Created Oct. 17, 2014 and submitted

lahosken
pants
148f907...
pants-reviews
jsirois, patricklaw, zundel

This change starts converting our docs from sphinx-powered-rst to Pants-enhanced-md, moving files to some different directories:

src/docs/*.md <= language-agnostic Pants-user docs

examples/src/java/com/pants/examples/*.md <= Pants-with-Java docs

examples/src/python/example/*.md <= Pants-with-py docs

src/python/pants/docs <= good place for pants-dev docs

Keeping foolang docs with examples/src/foolang feels right; if we change the examples, we probably want to change the docs, too. Less-certain about where language-agnostic docs go.

eyeball-compare pages gen'd from .rst, .md

  • 0
  • 0
  • 0
  • 4
  • 4
Description From Last Updated
IT
  1. Ship It!

  2. 
      
ZU
  1. I only got through the first file...

    1. Saved these excellent comments at https://github.com/pantsbuild/pants/issues/692

      This here change is converting some existing docs from .rst format like src/python/pants/docs/JVMProjects.rst to .md format like examples/src/java/com/pants/examples/readme.md .

      I'd like to keep this here change a format-change and do content-changes in another change.

  2. Is there really a 'goal jar'? Maybe this is out of date and should be 'goal binary'

  3. I am not sure what the --resolve-* parameters are. I don't see them.

  4. The directory is now: dist/hello-example-bundle

    $ ls dist/hello-example-bundle/
    greetee.txt hello-example.jar libs

  5. zundel/external-archive java -jar hello-example.jar
    Hello, Bundled-File World!
    Hello, Resource World!

  6. find . -ls
    80796630 0 drwxr-xr-x 5 zundel zundel 170 Oct 17 17:14 .
    80796636 8 lrwxr-xr-x 1 zundel zundel 90 Oct 17 17:14 ./greetee.txt -> /Users/zundel/Src/Pants/examples/src/java/com/pants/examples/hello/main/config/greetee.txt
    80796635 8 -rw-r--r-- 1 zundel zundel 3320 Oct 17 17:14 ./hello-example.jar
    80796631 0 drwxr-xr-x 2 zundel zundel 68 Oct 17 17:14 ./libs

  7. Just the name of the .jar file has changed, contents are the same:

    $ jar -tf ./hello-example.jar
    META-INF/
    META-INF/MANIFEST.MF
    com/
    com/pants/
    com/pants/examples/
    com/pants/examples/hello/
    com/pants/examples/hello/main/
    com/pants/examples/hello/main/HelloMain.class
    com/pants/example/
    com/pants/example/hello/
    com/pants/example/hello/world.txt
    com/pants/examples/hello/greet/
    com/pants/examples/hello/greet/Greeting.class

  8. I think its just the 'greeetee.txt' file now.

  9. 
      
ZU
  1. I took a gander just at formatting issues.

    Should I see any styling? Looks like no CSS is applied when I use ./build-support/bin/publish_docs_new.sh and then look at the resulting .html files.

    I see a lot of .codehilite in the documenet source, but I don't see any syntax highlighting in the code samples.

    1. Excellent feedback is excellent.

      Should I see any styling?

      If "styling" here means "syntax highlighting", you caught two bugs.

      • I should have added language hints to the copy-pasted code snippets. (yay, fixed, thanks to you)

      • The include-code-snippet code should add language hints or the Pygments equivalent. I'll start on that now. Prrrobably in a separate change, since it involves code.

      If "any styling" here means, "seriously, any styling", you caught more than two bugs, but I only notice those two. To me, these pages look gray, blue, and, uhm, stripe-y. But if you say "seriously", I'll look more closely

  2. FYI, this example isn't formatted the same way as the manually entered and indented one is below. (It doesn't have a grey background)

    1. Good catch. You might enjoy the "sandbox" site http://pantsbuild.github.io/sitegen-test/JVMProjects.html . That shows these pages with some formatting fixes from https://rbcommons.com/s/twitter/r/1178/ , including gray backgrounds

    2. I ran build-support/bin/publish_docs_new.sh and looked at the output that way. If the "sandbox" site is nice and stripe-y, as you say. The way I've been looking at is "suddenly its 1994" web style. Actually maybe a bit better than 1994 because tables seem to be working. Is there a way I can look at the sandbox way locally?

    3. Is there a way I can look at the sandbox way locally?

      Mmmmmaybe ./rbt patch 1178 , build-support/bin/publish_docs_new.sh ?

      The way I've been doing it, since I'm working on these things in separate branches:

      git checkout (newly-created-markdown-files branch)
      build-support/bin/publish_docs_new.sh

      now your dist/markdown/.... dir has "raw" .html for these pages

      git checkout (sitegen and stylish tweaks branch)
      get src/python/pants/docs/docsite.json from (newly-created-markdown-files branch) that you stashed a while back
      PANTS_DEV=1 build-support/bin/publish_docs_new.sh

      now you've applied tweaked sitegen code to "raw" .html from those pages

      Woo, janky

    4. Mmmmmaybe ./rbt patch 1178 , build-support/bin/publish_docs_new.sh ?

      uhm, prepend build-support/bin/publish_docs_new.sh with a PANTS_DEV=1 , lest a legit pants.pex prevent you from exercising that reviewboard's tweaked code.

  3. using cmd around the command, inconsistent with the ./pants goal ... below that are indented.

    1. good catch. fixed.

  4. indenting on this is weird.

    1. good catch. fixed.

  5. examples/src/python/example/readme.md (Diff revision 1)
     
     

    these don't come out looking any different in the rendered HTML. Most of the words like this are monospace font.

    1. good catch. fixed.

  6. 
      
LA
ZU
  1. I got through the whole thing, just a few other items...

  2. src/docs/build_files.md (Diff revision 2)
     
     

    FYI dead link. I'm sure it will fix itself when you convert the dictonary over.

  3. src/docs/build_files.md (Diff revision 2)
     
     

    I think this section is supposed to be a list of goals.

    list
    list ::
    depmap
    filedeps
    ...

    It doesn't render all that well, but I'm not sure what to suggest.

    1. Yeah. I gave up on "only fix formatting, not content" and changed the wording.

  4. src/docs/build_files.md (Diff revision 2)
     
     

    . and : both at the end of the sentence.

    1. good catch. fixed.

  5. src/docs/build_files.md (Diff revision 2)
     
     

    . and : both at the end of a sentence. This occurs several more times in this file.

    1. good catch. fixed.

  6. 
      
LA
ZU
  1. OK, this is coming along nicely. I can see it would be good to get everything converted over quickly so that we can make content changes without worrying about losing them in the markdown refactor.

  2. 
      
JS
  1. 
      
  2. build-support/bin/publish_docs_new.sh (Diff revision 3)
     
     

    Please wrap this up <= 100 cols

  3. Please kill trailing ws throughout

  4. 
      
PA
  1. 
      
    1. careful, you're looking at a doc for folks using an old version of Pants

    2. Oops, I see now.

  2. This is outdated and very wrong

  3. We should be encouraging ./pants goal binary, not ./pants <target> or ./pants build ...

  4. Ditto above, we should be using the goals.

  5. Deprecated

  6. 
      
PA
  1. Ship It!

  2. 
      
LA
ZU
  1. still lgtm

  2. 
      
LA
Review request changed

Status: Closed (submitted)

LA
  1. Thanks, folks! Submitted.

  2. 
      
Loading...