Making Beautiful Docs

3be105d0694009ef3928230a65af9eaa?s=47 Phil Ewels
February 27, 2020

Making Beautiful Docs

SciLifeLab Coffee & Code, Feb 27th 2020.

An informal discussion of different methods for writing, building and hosting documentation for your code projects.

3be105d0694009ef3928230a65af9eaa?s=128

Phil Ewels

February 27, 2020
Tweet

Transcript

  1. MAKING BEAUTIFUL DOCS C O F F E E &

    C O D E
  2. READ ON Writing Beautiful docs: P A R T O

    N E
  3. Coffee & Code / Feb 2020 CHOOSE YOUR AUDIENCE W

    R I T I N G B E A U T I F U L D O C U M E N T A T I O N Users Developers Future-you
  4. Coffee & Code / Feb 2020 CHOOSE YOUR STYLE W

    R I T I N G B E A U T I F U L D O C U M E N T A T I O N Comments Docstrings Free text
  5. Coffee & Code / Feb 2020 Docstrings • Often used

    for documenting APIs • Write docs as you write code, no context switching • Great if people need to use your code • Not very coherent by itself G r e a t f o r p e o p l e u s i n g y o u r c o d e
  6. Coffee & Code / Feb 2020 Free text • Write

    free text in prose • Can use markup languages (eg. Markdown) • Can use WYSIWYG editors • Code and documentation in separate files • Describe concepts and usage F o r p a c k a g e d t o o l s a n d p r o j e c t s
  7. Coffee & Code / Feb 2020 Automate writing Editor plugins

    Auto-generate docstrings and lint for missing variables Lint markdown text as you write, and on every push / PR
  8. Coffee & Code / Feb 2020 Visualise writing See your

    documentation WYSIWYM (what you see is what you mean) editors render in-place as you type Preview Markdown rendering as you type typora.io
  9. NEVER UNDERESTIMATE A README

  10. READ ON Building Beautiful docs: P A R T T

    W O
  11. Coffee & Code / Feb 2020 Online docs The basics

    Build Convert what you've written to HTML Host Make these HTML pages available on the web
  12. Coffee & Code / Feb 2020 DE-FACTO STANDARD • Free

    hosting • Multiple versions • Quick to get up and running • Autodoc docstrings!
  13. Coffee & Code / Feb 2020 GO YOUR OWN WAY

    • Autodoc docstrings! • Custom themes • Full customisation, plugins
  14. Coffee & Code / Feb 2020 LOOK MA! THEMES! •

    Auto-refresh local server • Lots of nice themes available • Markdown + YAML • Easy to customise • Also supported by Read the Docs MkDocs
  15. Coffee & Code / Feb 2020 RICH TEXT EASY EDIT

    • WYSIWYG editor for markdown • Bi-directional integration with GitHub • Free hosting + domain • Powerful addons, especially for web APIs
  16. Coffee & Code / Feb 2020 STATIC WEB BUILDERS •

    Build static sites from Markdown • Lots of templates available • Complete customisation possible
  17. Coffee & Code / Feb 2020 ROLL YOUR OWN •

    Convert markdown to HTML yourself • Build your own website • Total control over the output • Can add in additional functionality • More difficult than the alternatives
  18. READ ON Hosting Beautiful docs: P A R T T

    W O
  19. Coffee & Code / Feb 2020 WHAT YOU NEED •

    Update on commit • Automatically build HTML docs • Host web pages
  20. Coffee & Code / Feb 2020 • Renders Markdown /

    RST / others into HTML automatically • Comes for free when you use GitHub • Co-located with code • Impossible to customise aesthetics GitHub Repository
  21. Coffee & Code / Feb 2020 • Builds Spinx and

    MkDocs automatically • Free for open-source repos • readthedocs.io subdomain URL for free • Custom domain names possible Read the Docs
  22. Coffee & Code / Feb 2020 • Host any static

    HTML for free • github.io domain name for free • Custom domain names possible • Can build Jekyll websites automatically GitHub Pages
  23. Coffee & Code / Feb 2020 • Automate just about

    anything • Run any docs build tool for every commit • Push to a GitHub Pages branch • Upload HTML to any web server GitHub Actions
  24. Coffee & Code / Feb 2020 • Host your website

    anywhere you want • Build your website however you want • Style your website however you want • Probably not free Personal Hosting
  25. READ ON The GitHub API The wonderful world of: B

    O N U S
  26. Coffee & Code / Feb 2020 Triggers Web Hooks Ping

    a remote URL with a JSON payload when a given event happens R e a c t t o e v e n t s o n G i t H u b GitHub Actions Run a compute job with custom software and commands on a given trigger • Web hooks broadcast event information to other resources • GitHub Actions run jobs when requested
  27. Coffee & Code / Feb 2020 nf-core website Fetch details

    for all pipelines Releases, keywords, stars, downloads, clones, file tree, markdown documentation Repository statistics Clones, commits, issues, pull-requests, contributors, unique cloners Organisation settings Org members, repository settings, *membership visibility, *automated invites
  28. Coffee & Code / Feb 2020 nf-core website Check repo

    settings 27 setting tests across 48 repositories
  29. Coffee & Code / Feb 2020 nf-core website Check repo

    settings 27 setting tests across 48 repositories Fix repo settings Attempt to fix incorrect settings in one click
  30. Make Beautiful Docs! Phil Ewels phil.ewels@scilifelab.se tallphil ewels sphinx-doc.org readthedocs.org

    mkdocs.org jekyllrb.com gohugo.io pages.github.com Icons: thenounproject.com Theme: EASY gitbook.com typora.io Images: unsplash.com