It seems we’re always on the lookout for a workable inline code documentation system.\u00a0 The pros and cons of doing this are always fighting it out, with a significant con being that this tends towards overdocumentation.<\/p>\n
At any rate, I just read that the Python documentation switched over from LaTeX to reStructuredText<\/a>. \u00a0 One of the common drawbacks of inline documentation is that some nasty tags are required to markup the text.\u00a0 reStructuredText avoids this problem by using quite intuitive underlining, indentation and numeric lists, such that the documentation text is formatted essentially as one would format it for normal plaintext readability.<\/p>\n This is a sample python script<\/a> documented with\u00a0 reST. You can paste one of the docstrings into this online renderer<\/a> to see the sample output.\u00a0 Rendering would normally be done with Docutils<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" It seems we’re always on the lookout for a workable inline code documentation system.\u00a0 The pros and cons of doing this are always fighting it out, with a significant con being that this tends towards overdocumentation. At any rate, I just read that the Python documentation switched over from LaTeX to reStructuredText. \u00a0 One of […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[20],"tags":[],"class_list":["post-44","post","type-post","status-publish","format-standard","hentry","category-coding"],"_links":{"self":[{"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/44","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=44"}],"version-history":[{"count":0,"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=\/wp\/v2\/posts\/44\/revisions"}],"wp:attachment":[{"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=44"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=44"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.ryanburns.net\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=44"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}