Earlier quoted context omitted.
Github hosts your docs for free, with a custom domain name?
Github Pages doesn't cost money.
Custom domain is usually where sites look for revenue ops, though VC/MS money should last for a while.
MkDocs 1.0
11–20 of 45 posts
Re: MkDocs 1.0
#12Earlier quoted context omitted.
Github hosts your docs for free, with a custom domain name?
Yep, just search for DNS CNAME handling on GitHub docs. We put also Cloudflare DNS in front of it to get TLS/SSL but I've heard this is not necessary anymore nowadays.
It's not, GitHub automatically registers Let's Encrypt certs for custom domains :)
Re: MkDocs 1.0
#13How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
I'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs.
POSITIVES OF MkDocs over Sphinx
* Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText.
* MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/.
* Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/m...)
* Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjking/1upkeyboard-docs/blob/master/....)
The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience):
* If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc).
* Sphinx seems better for auto documentation for APIs and other code documentation.
Re: MkDocs 1.0
#14Earlier quoted context omitted.
Github hosts your docs for free, with a custom domain name?
Yep, just search for DNS CNAME handling on GitHub docs. We put also Cloudflare DNS in front of it to get TLS/SSL but I've heard this is not necessary anymore nowadays.
Cool, thanks. Looking at your yaml, it looks like the title of each doc has to be configured separately? Is that required?
Re: MkDocs 1.0
#15The proliferation of yaml is rather unfortunate.
Re: MkDocs 1.0
#16Earlier quoted context omitted.
Yep, just search for DNS CNAME handling on GitHub docs. We put also Cloudflare DNS in front of it to get TLS/SSL but I've heard this is not necessary anymore nowadays.
Cool, thanks. Looking at your yaml, it looks like the title of each doc has to be configured separately? Is that required?
No this is optional. You can also just throw a bunch of .md files in a directory structure and run mkdocs over it to generate a tree for navigation.
Re: MkDocs 1.0
#17Awesome and congrats. We started using MkDocs for https://aqueduct.io/docs/, and have since used it for a ton of projects. Some things that we found really useful were that it indexes all of your content for full text search automatically, and it’s stupid simple to deploy it to gh-pages. With a minimal amount of scripting, we push to a mkdocs source branch and it builds and deploys nearly immediately. It has saved us a ton of time and delivered tremendous value.
Re: MkDocs 1.0
#18Awesome and congrats. We started using MkDocs for https://aqueduct.io/docs/ , and have since used it for a ton of projects. Some things that we found really useful were that it indexes all of your content for full text search automatically, and it’s stupid simple to deploy it to gh-pages. With a minimal amount of scripting, we push to a mkdocs source branch and it builds and deploys nearly immediately. It has saved u…
Is that more efficient than building locally and pushing changes to a repo?
Re: MkDocs 1.0
#19Awesome and congrats. We started using MkDocs for https://aqueduct.io/docs/ , and have since used it for a ton of projects. Some things that we found really useful were that it indexes all of your content for full text search automatically, and it’s stupid simple to deploy it to gh-pages. With a minimal amount of scripting, we push to a mkdocs source branch and it builds and deploys nearly immediately. It has saved u…
Is that more efficient than building locally and pushing changes to a repo?
I’ve found that I’m at least more willing to make quick typo fixes and deploy them when I just have to make the change locally and do a single push. This is especially true (for me) when there is some additional web content that is not generated by mkdocs.
Re: MkDocs 1.0
#20We moved the majority of docs for our projects (https://github.com/2600hz) to use mkdocs to build our doc sites (https://docs.2600hz.com/dev https://docs.2600hz.com/ui etc).
I have a simple script that receives github webhooks on PR merges to master that fetches the latest version of master and builds the site. So from PR merge to the docs site being updated is now seconds of time.
We also integrated building the doc sites into our CI process so PRs will fail if they would cause mkdocs to fail to build the site (borked yaml, make sure docs are included in the yaml, other things).
This has been a boon for our community of users and developers. Coupled with our AST parsers that look for code changes that require doc changes, we're getting better about alerting developers of the need to document something, and reviewers of the need if the developer forgot. Not a panacea but has significantly improved doc coverage for Kazoo which has a broad set of APIs available to different types of users.
Cheers to 1.0!