automate your docs, automate yourself

28
Automate your Docs, automate yourself Yes… Test your Docs FOSDEM 2017 @chrischinch

Upload: chris-ward

Post on 11-Feb-2017

52 views

Category:

Technology


5 download

TRANSCRIPT

Page 1: Automate your docs, automate yourself

Automate your Docs, automate yourselfYes… Test your Docs 😁

FOSDEM 2017 @chrischinch

Page 2: Automate your docs, automate yourself

What’s one of the first things you look at

with a new project?

Page 3: Automate your docs, automate yourself

–Ken Williams, Perl

“Documentation is complete when

someone can use your project without having

to look at its code”

Page 4: Automate your docs, automate yourself

–Andy Mabbett, Wikimedia

“Documentation is like housework”

Page 5: Automate your docs, automate yourself
Page 6: Automate your docs, automate yourself

SpellingCathc those peski typos like teh.

Page 7: Automate your docs, automate yourself

Hunspell

sudo apt-get install hunspell

brew install hunspell

# Add dictionaries

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

Page 8: Automate your docs, automate yourself

markdown-spellcheck

npm install markdown-spellcheck -g

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

Page 9: Automate your docs, automate yourself

Spelling - Next steps• Custom dictionary

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

• CI

• Editors

• Other file types

Page 10: Automate your docs, automate yourself

Write betterLearn to write gooder

Page 11: Automate your docs, automate yourself

write-good

npm install write-good -g

write-good **/*.md

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

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

Page 12: Automate your docs, automate yourself

LanguageTool

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

Page 13: Automate your docs, automate yourself

Write better - Next steps

• CI

• Editors

Page 14: Automate your docs, automate yourself

ScreenshotsA picture says 1000 words

Page 15: Automate your docs, automate yourself

Robot framework

# Install PhantomJS

easy_install robotframework robotframework-selenium2library image robotframework-selenium2screenshots

robot folder

Page 16: Automate your docs, automate yourself

Screenshots - Next steps

• CI

Page 17: Automate your docs, automate yourself

TestingWhat use is broken code?

Page 18: Automate your docs, automate yourself

APIs - dredd

npm install dredd

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

Page 19: Automate your docs, automate yourself

Other options

• Jetman - Write tests in JavaScript

• Postman + Newman - Tests with desktop app

• Myriad commercial options

Page 20: Automate your docs, automate yourself

Code - Sphinx

sudo pip install Sphinx

make doctest

Page 21: Automate your docs, automate yourself

Testing - Next steps

• non-Python?

• CI

Page 22: Automate your docs, automate yourself

Bonus material

Do we have time?

Page 23: Automate your docs, automate yourself

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

Page 24: Automate your docs, automate yourself

Editor snippets

• Atom: Built in

• Vim: ultisnips, snipmate, xtemplate and more

• Emacs: Yasnippet

• Sublime: Built in

Page 25: Automate your docs, automate yourself

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

Page 26: Automate your docs, automate yourself

Want More?

• bit.ly/2dXs5nr

• coala.io

• testthedocs.org

• slack.writethedocs.org

Page 27: Automate your docs, automate yourself

–Me (maybe)

“Documentation isn’t just for developers”

Page 28: Automate your docs, automate yourself

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

I have stickers and merchandise!