Development Tools Release 2017.11.14
Total Page:16
File Type:pdf, Size:1020Kb
Development tools Release 2017.11.14 Patrick Vergain 2017-12-9 Contents 1 Documentation 3 1.1 Documentation news...........................................3 1.1.1 Documentation news 2017...................................3 1.1.2 Documentation news 2016...................................3 1.2 Documentation Advices.........................................4 1.2.1 You are what you document (Monday, May 5, 2014).....................4 1.2.2 13 Things People Hate about Your Open Source Docs.....................5 1.2.3 Beautiful docs..........................................5 1.2.4 Designing Great API Docs (11 Jan 2012)...........................5 1.2.5 Docness.............................................5 1.2.6 Hacking distributed (february 2013)..............................6 1.2.7 Jacob Kaplan-Moss (November 10, 2009)...........................6 1.2.8 Agile documentation best practices...............................6 1.2.9 Best Practices for Documenting Technical Procedures Melanie Seibert............7 1.2.10 Plone..............................................7 1.2.11 Twilio..............................................7 1.2.12 Other advices..........................................7 1.3 Documentation generators........................................ 10 1.3.1 Sphinx.............................................. 10 1.3.2 Authorea............................................ 144 1.3.3 Doxygen............................................ 144 1.3.4 Javadoc............................................. 159 1.3.5 Jekyll.............................................. 159 1.3.6 JSDoc.............................................. 160 1.3.7 Mkdocs............................................. 161 1.3.8 Pandoc............................................. 161 1.4 Good documentation........................................... 164 1.4.1 CakePHP............................................ 164 1.4.2 Passlib.............................................. 164 1.4.3 Sfepy.............................................. 164 1.4.4 Shark.............................................. 164 1.5 Formats Documentation......................................... 165 1.5.1 Input formats.......................................... 165 1.5.2 Input/output formats...................................... 174 1.5.3 Output formats......................................... 175 1.6 Documentation projects......................................... 179 i 1.6.1 C Documentation projects................................... 179 1.6.2 Documenting python projects.................................. 179 1.7 Documentation tools........................................... 180 1.7.1 Dash............................................... 180 1.7.2 Graphviz............................................ 182 1.7.3 Zeal documentation browser.................................. 182 1.8 Documentation videos.......................................... 183 1.8.1 Write the docs.......................................... 183 1.8.2 RTFM - wRite The Friendly Manual.............................. 183 1.9 Wiki documentation........................................... 184 1.9.1 Mediawiki............................................ 184 1.9.2 Wiki tools............................................ 195 2 Command Line Interface (CLI) 201 2.1 Introduction............................................... 201 2.2 Usage................................................... 202 2.2.1 CLI and python......................................... 202 2.2.2 CLI with Perl.......................................... 202 2.2.3 Command Line Interface (CLI) on GNU/linux......................... 207 2.2.4 Command Line Interface (CLI) on Windows.......................... 219 2.2.5 Google cli............................................ 231 3 Databases 233 3.1 PostgreSQL database........................................... 233 3.1.1 PostgreSQL books....................................... 233 ii Development tools, Release 2017.11.14 pvbookmarks Release 2017.11.14 Date 2017-12-9 Authors Patrick Vergain Target About documentation and CLI See also: • genindex • https://github.com/pvergain/pvbookmarks • http://pvbookmarks.readthedocs.org/en/master/ Contents 1 Development tools, Release 2017.11.14 2 Contents CHAPTER 1 Documentation See also: • http://blog.smartbear.com/software-quality/bid/256072/13-reasons-your-open-source-docs-make-people-want-to-scream • http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html 1.1 Documentation news 1.1.1 Documentation news 2017 Contents • Documentation news 2017 – Autodoc-style extraction into Sphinx for your JS project Autodoc-style extraction into Sphinx for your JS project See also: • sphinx-js : autodoc-style extraction into Sphinx for your JS project 1.1.2 Documentation news 2016 Contents • Documentation news 2016 3 Development tools, Release 2017.11.14 – La documentation linux utilise sphinx La documentation linux utilise sphinx See also: • https://github.com/return42/linuxdoc • https://return42.github.io/linuxdoc/ • https://lwn.net/Articles/692704/ L’annonce sur https://lwn.net/Articles/692704/ 1.2 Documentation Advices See also: • parse_API_doc • http://producingoss.com/en/getting-started.html • http://justwriteclick.com/book/ • http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html Contents • Documentation Advices – You are what you document (Monday, May 5, 2014) – 13 Things People Hate about Your Open Source Docs – Beautiful docs – Designing Great API Docs (11 Jan 2012) – Docness * Docness Source code – Hacking distributed (february 2013) – Jacob Kaplan-Moss (November 10, 2009) – Agile documentation best practices – Best Practices for Documenting Technical Procedures Melanie Seibert – Plone – Twilio – Other advices 1.2.1 You are what you document (Monday, May 5, 2014) See also: 4 Chapter 1. Documentation Development tools, Release 2017.11.14 • http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html • http://jacobian.org/writing/great-documentation/ • http://zachholman.com/posts/documentation/ • http://blog.parse.com/2012/01/11/designing-great-api-docs/ • http://www.mikepope.com/blog/DisplayBlog.aspx?permalink=1680 • https://github.com/PharkMillups/beautiful-docs • http://blog.codinghorror.com/if-it-isnt-documented-it-doesnt-exist/ • http://docs.writethedocs.org/writing/beginners-guide-to-docs/ The number one cause of startup failure is not the product, but the distribution: it doesn’t matter how good the product is if no one uses it. With software, the documentation is the distribution: it doesn’t matter how good the code is if no one uses it. If it isn’t documented, it doesn’t exist. 1.2.2 13 Things People Hate about Your Open Source Docs See also: • http://blog.smartbear.com/careers/13-things-people-hate-about-your-open-source-docs/ • http://www.framablog.org/index.php/post/2013/06/28/documentation-defauts-open-source 1.2.3 Beautiful docs See also: • https://github.com/PharkMillups/beautiful-docs 1.2.4 Designing Great API Docs (11 Jan 2012) See also: • http://blog.parse.com/2012/01/11/designing-great-api-docs/ 1.2.5 Docness See also: • http://docness.readthedocs.org/ • http://docness.readthedocs.org/en/latest/documentation-is-part-of-product.html Consider the documentation as a component of your product, i.e. don’t package it as an external product or as an option. In software development, your “product” is usually made of the software, which itself is usually based on source code. 1.2. Documentation Advices 5 Development tools, Release 2017.11.14 Docness Source code See also: https://github.com/benoitbryon/docness 1.2.6 Hacking distributed (february 2013) See also: • http://hackingdistributed.com/2013/02/11/principled-documentation/ In the beginning, there was no documentation. These days, infrastructure software has terrible documentation. Take heed of these commandments, for, among hackers, judgment day is every day. 1.2.7 Jacob Kaplan-Moss (November 10, 2009) See also: http://jacobian.org/writing/great-documentation/what-to-write/ 1.2.8 Agile documentation best practices See also: • http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm • http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm#sthash.nuUKabMJ.dpuf Ideally, an agile document is just barely good enough, or just barely sufficient, for the situation at hand. Documentation is an important part of agile software development projects, but unlike traditionalists who often see documentation as a risk reduction strategy, agilists typically see documentation as a strategy which increases overall project risk and therefore strive to be as efficient as possible when it comes to documentation. Agilists write documentation when that’s the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation. This article summarizes common “best practices” which agilists have adopted with respect to documentation. Best practices for increasing the agility of documentation: Writing Prefer executable specifications over static documents Document stable concepts, not speculative ideas Gen- erate system documentation Simplification Keep documentation just simple enough, but not too simple Write the fewest documents with least overlap Put the information in the most appropriate place Display information publicly Determining What to Document Document with a purpose Focus on the needs of the actual customers(s) of the document The customer determines sufficiency Determining When to Document Iterate, iterate, iterate Find better ways to communicate