-
Notifications
You must be signed in to change notification settings - Fork 182
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
Conversation
font-size: 14px; | ||
} | ||
|
||
code { |
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
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. |
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)
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!
@@ -0,0 +1,6 @@ | |||
# Concepts | |||
|
|||
Imagine a world without kittens. What a world that would be. |
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.
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
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.
Games aside, I like this approach. I wish there was a way to generate docs from the docstrings, but this is probably good enough. |
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 |
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!
* 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
color: #aa0000; | ||
} | ||
.highlight .kc { | ||
color: #000000; |
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
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.
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
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.
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. :)
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...
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.
🚀
@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:
These items were considered nice to have but not a hard requirement:
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:
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:
And a few disadvantages:
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!