8000 Enable GH-Pages Documentation by t8y8 · Pull Request #100 · tableau/document-api-python · GitHub
[go: up one dir, main page]

Skip to content

Enable GH-Pages Documentation #100

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

Merged
merged 1 commit into from
Oct 28, 2016
Merged

Enable GH-Pages Documentation #100

merged 1 commit into from
Oct 28, 2016

Conversation

t8y8
Copy link
Contributor
@t8y8 t8y8 commented Oct 24, 2016

@RussTheAerialist @benlower @LGraber ,

@jdomingu and I spent some time getting a docs pipeline working for the document api. This can extend to our other repos.

We approached it with the following requirements:

  • Documentation should be generated from Markdown
  • It should support fenced code blocks and tables (GFM)
  • The build should be locally testable
  • The deploy should be automatic on push to master
  • The tooling should be fairly simple to install/run

These items were considered nice to have but not a hard requirement:

  • Auto-Generated API documentation

My prototype made use of mkdocs because it's python, simple, and integrated nicely with travis.
I have a preference, can you tell :)

Mkdocs had a few cons:

  • Fine-Grained control over layout (custom layouts aren't supported until 0.16 which is unreleased)
  • Deploy to GH-Pages required a hand-written script in the repo and run from travis (But I got it working!!!)

The second approach, presented here, was to move to using the built in auto-generation-and-publish-to-gh-pages via Jekyll.

This has a few advantages:

  • No deploy script
  • Built in to Github
  • We can reuse the template(s) we're already using for the WDC

And a few disadvantages:

  • There are no build failures that we can check in travis, they will publish broken docs
  • The toolchain is more annoying (Gem, Bundle, Etc) than 'pip install' and you're off

To test docs changes locally:
bundle exec jekyll serve

Preview at: https://t8y8.github.io/document-api-python/

Once merged, we can enable GH-Pages and all pushes to master will get updates to the docs automatically.

I'm super excited about this, because I think accessible markdown documentation is important for our users to understand the library, and also as a good place to start contributing. Many first-timers start with docs!

font-size: 14px;
}

code {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's an example of how we can override some stuff in the themes.

I thought the code blocks were too small

creating a PR can be found in the [github documentation](https://help.github.com/articles/creating-a-pull-request/)

If the feature is complex or has multiple solutions that could be equally appropriate approaches, it would be helpful to file an issue to discuss the
design trade-offs of each solution before implementing, to allow us to collectively arrive at the best solution, which most likely exists in the middle somewhere.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couldn't this be a symlink to the upper-level contributing.md (I think we have one)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! Apparently I can!

@@ -0,0 +1,6 @@
# Concepts

Imagine a world without kittens. What a world that would be.
Copy link
Contributor
@graysonarts graysonarts Oct 24, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay seriously, last night we were playing the expansion to Betrayal at the House on the Hill, and the haunt was literally, you have to soothe kittens while preparing cat food for the large cat.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ha, love it! That's a great game

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Literally my favorite game of all times.

@graysonarts
Copy link
Contributor

Games aside, I like this approach. I wish there was a way to generate docs from the docstrings, but this is probably good enough.

@t8y8
Copy link
Contributor Author
t8y8 commented Oct 24, 2016

There are a few experimental plugins for mkdocs that we may be able to leverage as things mature:

It looks like the mkdocs authors are mostly concerned with having a clean simple feature set, and has a few ideas for a plugin api that could handle the rest. There's active discussion on their tracker.

I think it's ok, with the size of our current projects, to have manual docs -- and we can integrate docstring-generated items in the future

@@ -1,5 +1,5 @@
language: python

cache: pip
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! I learned something new about travis today!

* Jekyll Dependencies
* First draft of docs -- we'll improve once skeleton is in place
* Does not deploy yet, need to do taht in github settings page
@t8y8 t8y8 changed the title DO NOT MERGE: mkdocs prototype Enable GH-Pages Documentation Oct 27, 2016
color: #aa0000;
}
.highlight .kc {
color: #000000;
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be #1

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hahahahahaha

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@LGraber ? Not sure I understand your comments.

On another note, I agree with @t8y8 's assessment. Jekyll is a bit heavier weight, but in general much more flexible. I think it's worth it in the long run especially once we get close to outgrowing the gh-pages pipeline. For now, the automated publishing that we get by using jekyll makes up for many many other things.

Also, in my opinion, if the expectation is that users are just editing markdown, it's pretty hard to break the build. Yes, it's possible to commit something with odd formatting, but that wouldn't be caught by a build test anyway. Unless we implement an HTML parser and link validator (whether we go with mkdocs or jekyll really, either one) I don't think that we get a substantial benefit from doc testing.

TLDR I recommend we go with jekyll for the autopublishing and for consistency with the WDC. +Testing is hard for docs regardless of the framework.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was making a joke (which clearly wasn't funny). Need to go through it some more but I can't comment on colors. :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hahaha, my best guess was that you were a SKC fan -- but we all know they lost so...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀 :shipit:

@t8y8 t8y8 merged commit ceb17d3 into tableau:development Oct 28, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants
0