Skip to content
Permalink
Browse files

first commit

  • Loading branch information...
timothycrosley committed Aug 31, 2019
0 parents commit 7cf925101e4ffc5690f2952ac9ad0b7b0410b4f8
@@ -0,0 +1 @@
comment: off
@@ -0,0 +1,4 @@
[report]
exclude_lines =
pragma: no cover
raise NotImplementedError()
@@ -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

@@ -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
@@ -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

21 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.
@@ -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.

0 comments on commit 7cf9251

Please sign in to comment.
You can’t perform that action at this time.