Jekyll vs. Sphinx

[robinandeer]

Jekyll vs. Sphinx

• Jekyll was primarily intended as a blogging tool, Sphinx is a documentation-first tool.
  • Helpful templates for Jekyll exists https://github.com/bruth/jekyll-docs-template/
• Jekyll is a versatile tools that you can use for many things, Sphinx is something I would only use for Python documentation.
• Jekyll is written in Ruby (another dependency) whereas Sphinx is a highly standardised Python native tool.
• I've always enjoyed developing themes etc. more for Jekyll (built in auto-updating server) over Sphinx. With the new Jekyll 2.0 you can even compile SCSS files which hopefully is brought to GitHub soon.

  Markup: Markdown vs. ReStructuredText

I think Markdown is hands down simpler to read/write. I will keep writing my READMEs etc. in Markdown which makes Sphinx less appealing.

+1 Jekyll

Hosting: GitHub Pages vs. ReadTheDocs

• Both tools can automatically update the docs after a new commit push
• GitHub pages separates your docs to a specific branch but keeps everything together in the repo
• It's more straight forward to setup custom domains with ReadTheDocs

  Features

• Sphinx has the autodoc plugin which let's you pull in inline documentation and generate API docs (DRY)
  • I don't know if I find API docs super necessary, though. I think I'm just as likely to dig into the source code at GitHub straight away rather than reading a rendered version of it. My first instinct is to launch iPython and inspect the function docstring.
• Jekyll benefits from the tight GitHub integration, e.g. https://help.github.com/articles/mentions-on-github-pages

  Usability

• Sphinx has always been a bit of a mystery to me (e.g. how you have to predefine internal links)
• Jekyll supports (a subset?) of the excellent Liquid template language (similar to Jinja2)

[thinkhuman]

You might want to check out Mkdocs (here on Github). Python-based, like Sphinx, but takes Markdown. For me, The requirement for reStructuredText is a deal-breaker on Sphinx. I want Markdown, period. It's a fast, easy, flexible source format.

Also, check out this nifty and promising project: https://github.com/tomjohnson1492/documentation-theme-jekyll

[robinandeer]

I'm actually a contributor and have been using MkDocs in some recent projects :smile:

I think it's really nice to strive in this template to keep everything Python-native. MkDocs will probably replace Sphinx for me in the near future as I agree that writing Markdown is a "deal maker".

Thanks for the reminder!

[clayrisser]

Sphynx supports markdown http://www.sphinx-doc.org/en/stable/markdown.html

[robinandeer]

Hmm that looks interesting!

I do kind of like how Sphinx ties your source code with docs although I've mostly switched to using GitBook for more recent projects. Markdown support is a requirement either way.

Might be time to make a push on this project and look around how Python development has changed since last.

[maxatka]

My 5 cents for Sphinx: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html