Enable GH-Pages Documentation #100
Conversation
| font-size: 14px; | ||
| } | ||
|
|
||
| code { |
There was a problem hiding this comment.
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.
Couldn't this be a symlink to the upper-level contributing.md (I think we have one)
There was a problem hiding this comment.
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.
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.
Ha, love it! That's a great game
There was a problem hiding this comment.
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.
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.
@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.
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.
Hahaha, my best guess was that you were a SKC fan -- but we all know they lost so...
@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 servePreview 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!