first commit

.codecov.yml

@@ -0,0 +1 @@
+comment: off

.coveragerc

@@ -0,0 +1,4 @@
+[report]
+exclude_lines =
+    pragma: no cover
+    raise NotImplementedError()

.gitignore

@@ -0,0 +1,88 @@
+*.py[cod]
+.DS_Store
+# C extensions
+*.so
+
+# Packages
+*.egg
+*.egg-info
+build
+eggs
+.eggs
+parts
+var
+sdist
+develop-eggs
+.installed.cfg
+lib
+lib64
+MANIFEST
+
+# Installer logs
+pip-log.txt
+npm-debug.log
+pip-selfcheck.json
+
+# Unit test / coverage reports
+.coverage
+.tox
+nosetests.xml
+htmlcov
+.cache
+.pytest_cache
+.mypy_cache
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# SQLite
+test_exp_framework
+
+# npm
+node_modules/
+
+# dolphin
+.directory
+libpeerconnection.log
+
+# setuptools
+dist
+
+# IDE Files
+atlassian-ide-plugin.xml
+.idea/
+*.swp
+*.kate-swp
+.ropeproject/
+
+# Python3 Venv Files
+.venv/
+bin/
+include/
+lib/
+lib64
+pyvenv.cfg
+share/
+venv/
+.python-version
+
+# Cython
+*.c
+
+# Emacs backup
+*~
+
+# VSCode
+/.vscode
+
+# Automatically generated files
+docs/preconvert
+site/
+out
+poetry.lock
+

.travis.yml

@@ -0,0 +1,57 @@
+sudo: false
+language: python
+
+branches:
+  except:
+    - requires-io-master
+
+env:
+  global:
+    - CI_DEPS=codecov>=2.0.5
+    - CI_COMMANDS=codecov
+
+git:
+  depth: 10000
+
+matrix:
+  fast_finish: true
+  include:
+    - python: 3.5
+      env: TOXENV=py35
+      sudo: required
+    - python: 3.6
+      env: TOXENV=py36
+      sudo: required
+    - python: 3.6
+      env: TOXENV=lint
+    - python: "3.7-dev"
+      env: TOXENV=py37
+
+install:
+  - pip install tox virtualenv setuptools
+
+script:
+  # All these steps MUST succeed for the job to be successful!
+  # Using the after_success block DOES NOT capture errors.
+  # Pull requests might break our build - we need to check this.
+  # Pull requests are not allowed to upload build artifacts - enforced by cibuild script.
+  - |
+    if [[ $TRAVIS_COMMIT_MESSAGE = *"[notest]"* ]]; then
+      echo "!!!! Skipping tests."
+    else
+      tox -- --verbose --cov-report=term
+    fi
+
+
+notifications:
+  slack:
+      -rooms:
+          mitmproxy:YaDGC9Gt9TEM7o8zkC2OLNsu
+      on_success: change
+      on_failure: change
+      on_start: never
+
+cache:
+  directories:
+    - $HOME/.pyenv
+    - $HOME/.cache/pip

CHANGELOG.md

@@ -0,0 +1,23 @@
+Install the latest
+===================
+
+To install the latest version of pdocs simply run:
+
+`pip3 install pdocs`
+
+OR
+
+`poetry add pdocs`
+
+OR
+
+`pipenv install pdocs`
+
+see the [Installation QuickStart](https://timothycrosley.github.io/portray/docs/quick_start/1.-installation/) for more instructions.
+
+Changelog
+=========
+
+## 1.0.0 - TBD
+Initial API stable release of pdocs
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Timothy Crosley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,99 @@
+
+[![Build Status](https://travis-ci.org/mitmproxy/pdoc.svg?branch=master)](https://travis-ci.org/mitmproxy/pdoc)
+[![PyPI Version](https://shields.mitmproxy.org/pypi/v/pdoc.svg)](https://pypi.org/project/pdoc/)
+
+`pdoc` is a library and a command line program to discover the public
+interface of a Python module or package. The `pdoc` script can be used to
+generate plain text or HTML of a module's public interface, or it can be used
+to run an HTTP server that serves generated HTML for installed modules.
+
+
+Installation
+------------
+
+    pip install pdoc
+
+
+Features
+--------
+
+* Support for documenting data representation by traversing the abstract syntax
+  to find docstrings for module, class and instance variables.
+* For cases where docstrings aren't appropriate (like a
+  [namedtuple](http://docs.python.org/2.7/library/collections.html#namedtuple-factory-function-for-tuples-with-named-fields)),
+  the special variable `__pdoc__` can be used in your module to
+  document any identifier in your public interface.
+* Usage is simple. Just write your documentation as Markdown. There are no
+  added special syntax rules.
+* `pdoc` respects your `__all__` variable when present.
+* `pdoc` will automatically link identifiers in your docstrings to its
+  corresponding documentation.
+* When `pdoc` is run as an HTTP server, external linking is supported between
+  packages.
+* The `pdoc` HTTP server will cache generated documentation and automatically
+  regenerate it if the source code has been updated.
+* When available, source code for modules, functions and classes can be viewed
+  in the HTML documentation.
+* Inheritance is used when possible to infer docstrings for class members.
+
+The above features are explained in more detail in pdoc's documentation.
+
+`pdoc` is compatible with Python 3.5 and newer.
+
+
+Example usage
+-------------
+`pdoc` will accept a Python module file, package directory or an import path.
+For example, to view the documentation for the `csv` module in the console:
+
+    pdoc csv
+
+Or, you could view it by pointing at the file directly:
+
+    pdoc /usr/lib/python3.7/csv.py
+
+Submodules are fine too:
+
+    pdoc multiprocessing.pool
+
+You can also filter the documentation with a keyword:
+
+    pdoc csv reader
+
+Generate HTML with the `--html` switch:
+
+    pdoc --html csv
+
+A file called `csv.m.html` will be written to the current directory.
+
+Or start an HTTP server that shows documentation for any installed module:
+
+    pdoc --http
+
+Then open your web browser to `http://localhost:8080`.
+
+There are many other options to explore. You can see them all by running:
+
+    pdoc --help
+
+
+Submodule loading
+-----------------
+
+`pdoc` uses idiomatic Python when loading your modules. Therefore, for `pdoc` to
+find any submodules of the input module you specify on the command line, those
+modules must be available through Python's ordinary module loading process.
+
+This is not a problem for globally installed modules like `sys`, but can be a
+problem for your own sub-modules depending on how you have installed them.
+
+To ensure that `pdoc` can load any submodules imported by the modules you are
+generating documentation for, you should add the appropriate directories to your
+`PYTHONPATH` environment variable.
+
+For example, if a local module `a.py` imports `b.py` that is installed as
+`/home/jsmith/pylib/b.py`, then you should make sure that your `PYTHONPATH`
+includes `/home/jsmith/pylib`.
+
+If `pdoc` cannot load any modules imported by the input module, it will exit
+with an error message indicating which module could not be loaded.