Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Making Beautiful Documentation


Published on

SciLifeLab Coffee & Code, Feb 27th 2020.

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

Published in: Science
  • Be the first to comment

  • Be the first to like this

Making Beautiful Documentation

  2. 2. READ ON Writing Beautiful docs: PARTONE
  3. 3. Coffee&Code/Feb2020 CHOOSE YOUR AUDIENCE WRITINGBEAUTIFULDOCUMENTATION Users Developers Future-you
  4. 4. Coffee&Code/Feb2020 CHOOSE YOUR STYLE WRITINGBEAUTIFULDOCUMENTATION Comments Docstrings Free text
  5. 5. Coffee&Code/Feb2020 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. 6. Coffee&Code/Feb2020 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. 7. Coffee&Code/Feb2020 Automate writing Editor plugins Auto-generate docstrings and lint for missing variables Lint markdown text as you write, and on every push / PR
  8. 8. Coffee&Code/Feb2020 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
  10. 10. READ ON Building Beautiful docs: PARTTWO
  11. 11. Coffee&Code/Feb2020 Online docs The basics Build Convert what you've written to HTML Host Make these HTML pages available on the web
  12. 12. Coffee&Code/Feb2020 DE-FACTO STANDARD • Free hosting • Multiple versions • Quick to get up and running • Autodoc docstrings!
  13. 13. Coffee&Code/Feb2020 GO YOUR OWN WAY • Autodoc docstrings! • Custom themes • Full customisation, plugins
  14. 14. Coffee&Code/Feb2020 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. 15. Coffee&Code/Feb2020 RICH TEXT EASY EDIT • WYSIWYG editor for markdown • Bi-directional integration with GitHub • Free hosting + domain • Powerful addons, especially for web APIs
  16. 16. Coffee&Code/Feb2020 STATIC WEB BUILDERS • Build static sites from Markdown • Lots of templates available • Complete customisation possible
  17. 17. Coffee&Code/Feb2020 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. 18. READ ON Hosting Beautiful docs: PARTTWO
  19. 19. Coffee&Code/Feb2020 WHAT YOU NEED • Update on commit • Automatically build HTML docs • Host web pages
  20. 20. Coffee&Code/Feb2020 • 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. 21. Coffee&Code/Feb2020 • Builds Spinx and MkDocs automatically • Free for open-source repos • subdomain URL for free • Custom domain names possible Read the Docs
  22. 22. Coffee&Code/Feb2020 • Host any static HTML for free • domain name for free • Custom domain names possible • Can build Jekyll websites automatically GitHub Pages
  23. 23. Coffee&Code/Feb2020 • 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. 24. Coffee&Code/Feb2020 • Host your website anywhere you want • Build your website however you want • Style your website however you want • Probably not free Personal Hosting
  25. 25. READ ON The GitHub API The wonderful world of: BONUS
  26. 26. Coffee&Code/Feb2020 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. 27. Coffee&Code/Feb2020 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. 28. Coffee&Code/Feb2020 nf-core website Check repo settings 27 setting tests across 48 repositories
  29. 29. Coffee&Code/Feb2020 nf-core website Check repo settings 27 setting tests across 48 repositories Fix repo settings Attempt to fix incorrect settings in one click
  30. 30. Make Beautiful Docs! Phil Ewels tallphilewels Icons: Theme: EASY Images: