Tired of keeping your documentation up-to-date with your library code?
Tired of users logging bus because your documentation is out of date?
If you write user documentation in Markdown, you can have guaranteed-working documentation using Simon Cropp's Markdown Snippets - https://github.com/SimonCropp/MarkdownSnippets.
2. 2
Recently…
• I needed to quickly try these Catch2 macros:
– TEMPLATE_TEST_CASE_METHOD_SIG
– TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG
• The docs had code samples.
3. 3
Easy – I’ll copy the
sample code from
the docs, and build
that!
9. 9
Now what?
Search for missing
symbol in docs –
No...
Search the whole
repo for similar code
10. 10
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Search the whole
repo for similar code
11. 11
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Paste in the relevant
missing bit…
Search the whole
repo for similar code
12. 12
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Paste in the relevant
missing bit…
Search the whole
repo for similar code
Test it – it works!
13. 13
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Paste in the relevant
missing bit…
Search the whole
repo for similar code
Test it – it works!
Fix the docs and
submit a pull
request – of course
25. 25
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s) whole file(s)
{ }some text to insert
in to documentation,
such as a test output
file
26. 26
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s) whole file(s)
{ }
mdsnippets
some text to insert
in to documentation,
such as a test output
file
27. 27
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s) whole file(s)
{ }
mdsnippets
.md
…..
…..
…..
snippet source
Easily view
Source and
Context
some text to insert
in to documentation,
such as a test output
file