Post on 11-Feb-2017
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!