Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The unsung hero of Python Programming - Documentation by Brett Drury

The unsung hero of Python Programming - Documentation by Brett Drury

The unsung hero of Python Programming - Documentation

DevOpsPorto

August 08, 2019
Tweet

More Decks by DevOpsPorto

Other Decks in Technology

Transcript

  1. The unsung hero of Python
    Programming - Documentation
    OR: How I Learned to Stop Worrying and Love Documentation
    Brett Drury Skim Technologies

    View Slide

  2. whisper.sh
    Majority of a Programmer’s Time is Working With
    1. Other People's’ Code
    2. Historical Code
    3. Third Party Libraries
    We tend to forget over-time why we have done
    things.
    1. Not using best practises (technical debt)
    2. Not Documenting Code
    Wastes Time.
    Worse Still When Developers Quit They Will
    Take Knowledge With Them

    View Slide

  3. Why I am interested in documentation?
    Worked for a number of companies where there
    was:
    1. A complicated codebase
    2. Minimal Documentation
    3. Lack of developer motivation to document
    4. Ethos of “good code documents itself”
    1st Task of New Position:
    Document codebase to prepare for growth

    View Slide

  4. projects.raspberrypi.org
    Pydoc - Python’s Documentation
    Tool
    1. Works with Doc Strings
    Generates documentation as HTML. Shows
    dependencies between Classes / Modules
    1. Static Web Pages
    2. Web-Server which connects all classes
    3. Including 3rd party libraries if it has doc-
    strings

    View Slide

  5. View Slide

  6. Commenting V Documentation
    “Code tells you how; Comments tell you why.”
    Jeff Atwood
    In general, commenting is describing your code
    to/for developers. The intended main audience is
    the maintainers and developers of the Python
    code.
    realpython.com
    Documenting code is describing its use and
    functionality to your users.
    realpython.com
    wikipedia

    View Slide

  7. Doc Strings
    The doc string line should begin with a capital letter
    and end with a period.
    The first line should be a short description.
    Don't write the name of the object.
    If there are more lines in the documentation string,
    the second line should be
    blank, visually separating the summary from the
    rest of the description.
    The following lines should be one or more
    paragraphs describing the object’s
    calling conventions, its side effects, etc.
    pythonforbeginners.com

    View Slide

  8. Package and Module Docstrings
    Package docstrings should be placed at the top of the
    package’s __init__.py file. This docstring should list
    the modules and sub-packages that are exported by
    the package.
    Module docstrings are placed at the top of the file
    even before any imports.
    realpython.com
    Sphynx has arguably replaced pydoc. It is a better renderer, with an option to render to Latex which then
    can be transformed into pdf.

    View Slide

  9. Related Packages
    pygments: Is a generic syntax highlighter suitable for
    use in code hosting, forums, wikis or other applications that
    need to prettify source code
    pydocstyle: is a static analysis tool for checking
    compliance with Python docstring conventions.
    Readthedocs: A way of hosting private and
    public documentation
    Type Hints
    Add hints to variables which can add information to the
    declared variables. For example:
    def testfunction(param1:int, param2:int):
    This will be reflected in the generated documentation

    View Slide

  10. Testing as Documentation (DocTest)
    1. Unit Tests expressed as doc-strings can
    be used as documentation.
    2. Unit Tests expressed as doc-strings can
    be used as unit tests
    def my_function(a, b):
    """
    >>> my_function(2, 3)
    6
    >>> my_function('a', 3)
    'aaa'
    """
    return a * b
    Trying:
    my_function(2, 3)
    Expecting:
    6
    ok
    Trying:
    my_function('a', 3)
    Expecting:
    'aaa'
    ok
    1 items had no tests:
    doctest_simple_with_docs
    1 items passed all tests:
    2 tests in doctest_simple_with_docs.my_function
    2 tests in 2 items.
    2 passed and 0 failed.
    Test passed.

    View Slide

  11. Recovering UML from Python Code
    Although we should write UML diagrams before
    we write code. It is possible to obtain UML
    diagrams on a post-hoc basis.
    PyReverse -> Now part of Pylint

    View Slide

  12. Good documentation in Python
    Does not have to take huge amount of time
    There are good number of tools that can cut
    the tedium from documentation
    Good code does not document itself, but
    assists existing documentation
    Helps new starters quickly learn the
    codebase
    Limits knowledge exiting the business

    View Slide

  13. Contact: [email protected]
    I also have research interests and still publish:
    Causal inference from text
    Bayesian Reasoning for Natural Language
    Event prediction from text
    Get in contact if you want to undertake some academic
    research and publish it.

    View Slide