tested and correct, how to make sure your documentation keeps working
TRANSCRIPT
tested and correcthow to make sure your documentation keeps working
adam dangoorsoftware developer at clusterhq
[email protected] @adamdangoor
https://github.com/adamtheturtle
the plan
the problem
the problem
the problem
the problem
the traditional way
•
•
•
the traditional way
• memory
•
•
the traditional way
• memory
• periodic review
•
the traditional way
• memory
• periodic review
• user feedback
why this is terrible
• software interacts with other software which changes without warning
•
•
•
why this is terrible
• software interacts with other software which changes without warning
• memory is imperfect
•
•
why this is terrible
• software interacts with other software which changes without warning
• memory is imperfect
• we have better things to do
•
why this is terrible
• software interacts with other software which changes without warning
• memory is imperfect
• we have better things to do
• user feedback is not guaranteed
a better way
software testing
link checking
sphinx.builders.linkcheck.CheckExternalLinksBuilder
spell checking
sphinxcontrib-spelling
that is just the start
flocker install instructions.. code-block:: console
alice@mercury:~$ brew tap ClusterHQ/tap ... alice@mercury:~$ brew install flocker-1.2.0 ... alice@mercury:~$ brew test flocker-1.2.0 ... alice@mercury:~$
if change is hard, we stagnate
flocker install instructions (part two)
.. task:: test_homebrew flocker-|latest-installable| :prompt: alice@mercury:~$
def task_test_homebrew(recipe): return sequence([ run_from_args(['brew', 'tap', 'ClusterHQ/tap']), run("brew update"), run("brew install {recipe}".format(recipe=recipe)), run("brew test {recipe}".format(recipe=recipe)), ])
command line outputjust use wordish
https://pypi.python.org/pypi/wordish
changing the organisational model
“organizations which design systems ... are constrained to produce designs which are copies of the communication
structures of these organizations”
–melvin conway
code then document
code and document
what to do about it
generating documentation
generating documentation
sphinx.ext.autodoc
class Word(object): """ A string which can be represented by a list of strings which are each valid tiles. """
generating documentation
generating documentation
selenium
generating documentation
selenium
~/Documents/boggle-solver/docs$ git diffdiff --git a/docs/results.html b/docs/results.htmlindex 776e5e0..7fff02c 100644--- a/docs/results.html+++ b/docs/results.html@@ -2,7 +2,7 @@ <head> <style> .results {- background-color: #b0c4de; + background-color: green; font-family: helvetica; } </style>
generating documentation
selenium
summary
hold on a minute
close, but no {cigar, ai}
associate tests and docs
other benefits
thank you for listening