automate your docs, automate yourself

Automate your Docs, automate yourselfYes… Test your Docs 😁

FOSDEM 2017 @chrischinch

What’s one of the first things you look at

with a new project?

–Ken Williams, Perl

“Documentation is complete when

someone can use your project without having

to look at its code”

–Andy Mabbett, Wikimedia

“Documentation is like housework”

SpellingCathc those peski typos like teh.

Hunspell

sudo apt-get install hunspell

brew install hunspell

# Add dictionaries

hunspell -u3 -H -d en_US **/*.md

markdown-spellcheck

npm install markdown-spellcheck -g

mdspell -r -n -a --en-us **/*.md

Spelling - Next steps• Custom dictionary

• suares.com/index.php?page_id=25&news_id=233

• CI

• Editors

• Other file types

Write betterLearn to write gooder

write-good

npm install write-good -g

write-good **/*.md

write-good **/*.md --weasel --so

write-good **/*.md --no-passive

LanguageTool

java -jar /Users/chrisward/Workspace/LanguageTool-3.6/languagetool-commandline.jar -l en-US "index.md"

Write better - Next steps

• CI

• Editors

ScreenshotsA picture says 1000 words

Robot framework

# Install PhantomJS

easy_install robotframework robotframework-selenium2library image robotframework-selenium2screenshots

robot folder

Screenshots - Next steps

• CI

TestingWhat use is broken code?

APIs - dredd

npm install dredd

dredd out/cda.apib https://cdn.contentful.com --hookfiles=./test-hooks.js

Other options

• Jetman - Write tests in JavaScript

• Postman + Newman - Tests with desktop app

• Myriad commercial options

Code - Sphinx

sudo pip install Sphinx

make doctest

Testing - Next steps

• non-Python?

• CI

Bonus material

Do we have time?

Multiformat - Pandocfor filename in **/*.md; do

pandoc --from=markdown+yaml_metadata_block --smart -o "$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename

pandoc --from=markdown+yaml_metadata_block --smart -o "$(basename "$filename" .md)".html --latex-engine=xelatex $filename

done

Editor snippets

• Atom: Built in

• Vim: ultisnips, snipmate, xtemplate and more

• Emacs: Yasnippet

• Sublime: Built in

Placeholders - sedif [[ $2 == "preview" ]]; then

sed -i -e 's/<access_token>/46cc338e0d4647e3b9f98c52615a2414d725b6ddffdbbb2f3bed26f73789dd53/g' $result_string

else

sed -i -e 's/<access_token>/297e67b247c1a77c1a23bb33bf4c32b81500519edd767a8384a4b8f8803fb971/g' $result_string

fi

Want More?

• bit.ly/2dXs5nr

• coala.io

• testthedocs.org

• slack.writethedocs.org

–Me (maybe)

“Documentation isn’t just for developers”

Thank You!Chris Ward contentful.com gregariousmammal.com @chrischinch

I have stickers and merchandise!