GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Enable GH-Pages Documentation by t8y8 · Pull Request #100 · tableau/document-api-python

Conversation

@t8y8

@t8y8 t8y8 commented Oct 24, 2016 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

@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!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
t8y8
t8y8 commented Oct 24, 2016
View reviewed changes
Comment thread docs/css/extra.css
font-size: 14px;
}

code {

@t8y8 t8y8 Oct 24, 2016

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
graysonarts
graysonarts reviewed Oct 24, 2016
View reviewed changes
Comment thread docs/contributing.md Outdated
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.

@graysonarts graysonarts Oct 24, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

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)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@t8y8 t8y8 Oct 24, 2016

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Yes! Apparently I can!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
graysonarts
graysonarts reviewed Oct 24, 2016
View reviewed changes
Comment thread docs/user-guide.md Outdated
@@ -0,0 +1,6 @@
# Concepts

Imagine a world without kittens. What a world that would be.

@graysonarts graysonarts Oct 24, 2016 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@t8y8 t8y8 Oct 24, 2016

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@graysonarts graysonarts Oct 24, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@graysonarts

graysonarts commented Oct 24, 2016

Copy link
Copy Markdown
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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@t8y8

t8y8 commented Oct 24, 2016 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor Author

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

  • Plugin API. mkdocs/mkdocs#206
  • https://github.com/erichulser/mkdocs_autodoc/

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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
graysonarts
graysonarts reviewed Oct 25, 2016
View reviewed changes
Comment thread .travis.yml
@@ -1,5 +1,5 @@
language: python

cache: pip

@graysonarts graysonarts Oct 25, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

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!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
t8y8 reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@t8y8
Adding docs that will build via Github Pages
af42a55 
* 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
LGraber
LGraber reviewed Oct 28, 2016
View reviewed changes
Comment thread docs/css/github-highlight.css
color: #aa0000;
}
.highlight .kc {
color: #000000;

@LGraber LGraber Oct 28, 2016

Copy link
Copy Markdown

There was a problem hiding this comment.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@t8y8 t8y8 Oct 28, 2016

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

@jdomingu ?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@LGraber LGraber Oct 28, 2016

Copy link
Copy Markdown

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Hahahahahaha

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@jdomingu jdomingu Oct 28, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@LGraber LGraber Oct 28, 2016

Copy link
Copy Markdown

There was a problem hiding this comment.

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. :)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@t8y8 t8y8 Oct 28, 2016

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

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...

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@benlower benlower Oct 28, 2016

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

🚀 :shipit:

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@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

Reviewers

@LGraber LGraber LGraber left review comments
+3 more reviewers
@graysonarts graysonarts graysonarts left review comments
@benlower benlower benlower left review comments
@jdomingu jdomingu jdomingu left review comments
Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@t8y8 @graysonarts @benlower @jdomingu @LGraber
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.