chore: Initial commit

.cruft.json

@@ -0,0 +1,24 @@
+{
+    "template": "https://github.com/pawamoy/cookie-poetry",
+    "commit": "39e751de4fda3c136fee27778e661365a47b9b2a",
+    "context": {
+        "cookiecutter": {
+            "project_name": "mkdocstrings",
+            "project_description": "Automatic documentation from docstrings, for mkdocs.",
+            "author_fullname": "Timothée Mazzucotelli",
+            "author_email": "pawamoy@pm.me",
+            "author_username": "pawamoy",
+            "repository_provider": "gitlab.com",
+            "repository_namespace": "pawamoy",
+            "repository_name": "mkdocstrings",
+            "copyright_holder": "Timothée Mazzucotelli",
+            "copyright_holder_email": "pawamoy@pm.me",
+            "copyright_date": "2019",
+            "copyright_license": "ISC License",
+            "python_package_distribution_name": "mkdocstrings",
+            "python_package_import_name": "mkdocstrings",
+            "python_package_command_line_name": "mkdocstrings",
+            "_template": "https://github.com/pawamoy/cookie-poetry"
+        }
+    }
+}

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+max-line-length = 120
+select = C,E,F,W,B,B950
+ignore = E501,W503,E203
+

.gitignore

@@ -0,0 +1,11 @@
+.idea/
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+build/
+.coverage
+tests/tmp/*
+!tests/tmp/.gitkeep
+pip-wheel-metadata/
+.pytest_cache/

.gitlab-ci.yml

@@ -0,0 +1,65 @@
+variables:
+    PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip"
+
+cache:
+  key: "${CI_JOB_NAME}"
+  paths:
+    - .cache/pip
+    - .venv
+
+stages:
+  - quality
+  - tests
+
+.install-deps-template: &install-deps
+  before_script:
+    - pip install poetry
+    - poetry --version
+    - poetry config settings.virtualenvs.in-project true
+    - poetry install -vv
+
+# Quality jobs
+
+.quality-template: &quality
+  <<: *install-deps
+  image: python:3.6
+  stage: quality
+
+check-bandit:
+  <<: *quality
+  script: make check-bandit
+
+check-black:
+  <<: *quality
+  script: make check-black
+
+check-flake8:
+  <<: *quality
+  script: make check-flake8
+
+check-isort:
+  <<: *quality
+  script: make check-isort
+
+check-safety:
+  <<: *quality
+  script: make check-safety
+
+# Tests jobs
+
+.test-template: &test
+  <<: *install-deps
+  stage: tests
+  script: make test
+
+python3.6:
+  <<: *test
+  image: python:3.6
+
+python3.7:
+  <<: *test
+  image: python:3.7
+
+python3.8:
+  <<: *test
+  image: python:3.8

.python-version

@@ -0,0 +1 @@
+3.6.8

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at pawamoy@pm.me. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+Contributions are welcome, and they are greatly appreciated!
+
+Every little bit helps, and credit will always be given.
+
+For bug reports, feature requests, and feedback,
+simply create a new [issue][1].
+Try to be as descriptive as possible.
+
+### Bug fixes, new features and documentation
+This project is developed using [`poetry`](https://github.com/sdispater/poetry).
+Follow the recommended installation method:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
+```
+
+Then follow these instructions:
+
+1. Fork the repository [on gitlab.com][2];
+1. Clone it on your machine;
+1. Go into the directory, and run `poetry install` to setup the development environment;
+1. Create a new branch with `git checkout -b bug-fix-or-feature-name`;
+1. Code!
+1. **Write tests. Run them all.** The commands to run the tests are:
+   ```bash
+   poetry run pytest  # to run all tests sequentially
+   poetry run pytest -v  # to print one test per line
+   poetry run pytest -n 4  # to run tests in parallel (4 workers)
+   poetry run pytest tests/test_api.py  # to run tests in a specific file
+   ```
+
+   `pytest` provides the `-k` option to select tests based on their names:
+
+   ```bash
+   poetry run pytest -k "api and remove"
+   poetry run pytest -k "utils or stats"
+   ```
+
+   See the [documentation for the `-k` option][3] for more examples.
+
+   A [Makefile](Makefile) is available for convenience: `make test`.
+1. When the tests pass, commit
+  (make sure to have atomic commits and contextual commit messages!
+  [Check out this awesome blog post by Chris Beams for more information.][4])
+1. Push;
+1. ...and finally, create a new [pull/merge request][5]!
+   Make sure to follow the guidelines.
+
+[1]: https://gitlab.com/pawamoy/mkdocstrings/issues/new
+[2]: https://gitlab.com/pawamoy/mkdocstrings
+[3]: https://docs.pytest.org/en/latest/example/markers.html#using-k-expr-to-select-tests-based-on-their-name
+[5]: http://chris.beams.io/posts/git-commit/
+[4]: https://gitlab.com/pawamoy/mkdocstrings/compare

CREDITS.md

@@ -0,0 +1 @@
+# Credits

LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2019, Timothée Mazzucotelli
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Makefile

@@ -0,0 +1,91 @@
+.DEFAULT_GOAL := help
+
+PY_SRC := src/ tests/ scripts/*.py docs/conf.py
+
+.PHONY: build
+build:  ## Build the package wheel and sdist.
+	poetry build
+
+.PHONY: check
+check: check-bandit check-black check-flake8 check-isort check-safety  ## Check it all!
+
+.PHONY: check-bandit
+check-bandit:  ## Check for security warnings in code using bandit.
+	poetry run bandit -r src/
+
+.PHONY: check-black
+check-black:  ## Check if code is formatted nicely using black.
+	poetry run black --check $(PY_SRC)
+
+.PHONY: check-flake8
+check-flake8:  ## Check for general warnings in code using flake8.
+	poetry run flake8 $(PY_SRC)
+
+.PHONY: check-isort
+check-isort:  ## Check if imports are correctly ordered using isort.
+	poetry run isort -c -rc $(PY_SRC)
+
+.PHONY: check-pylint
+check-pylint:  ## Check for code smells using pylint.
+	poetry run pylint $(PY_SRC)
+
+.PHONY: check-safety
+check-safety:  ## Check for vulnerabilities in dependencies using safety.
+	poetry run pip freeze 2>/dev/null | \
+		grep -v mkdocstrings | \
+		poetry run safety check --stdin --full-report 2>/dev/null
+
+.PHONY: clean
+clean: clean-tests  ## Delete temporary files.
+	@rm -rf build 2>/dev/null
+	@rm -rf dist 2>/dev/null
+	@rm -rf src/*.egg-info 2>/dev/null
+	@rm -rf .coverage* 2>/dev/null
+	@rm -rf .pytest_cache 2>/dev/null
+	@rm -rf pip-wheel-metadata 2>/dev/null
+
+.PHONY: clean-tests
+clean-tests:  ## Delete temporary tests files.
+	@rm -rf tests/tmp/* 2>/dev/null
+
+.PHONY: credits
+credits:  ## Regenerate CREDITS.md.
+	poetry run ./scripts/gen-credits-data.py | \
+		poetry run jinja2 --strict -o CREDITS.md --format=json scripts/templates/CREDITS.md -
+
+.PHONY: docs
+docs:  ## Build the documentation locally.
+	poetry run sphinx-build -E -b html docs build/docs
+
+.PHONY: help
+help:  ## Print this help.
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z0-9_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
+
+.PHONY: lint
+lint: lint-black lint-isort  ## Run linting tools on the code.
+
+.PHONY: lint-black
+lint-black:  ## Lint the code using black.
+	poetry run black $(PY_SRC)
+
+.PHONY: lint-isort
+lint-isort:  ## Sort the imports using isort.
+	poetry run isort -y -rc $(PY_SRC)
+
+.PHONY: publish
+publish:  ## Publish the latest built version on PyPI.
+	poetry publish
+
+.PHONY: setup
+setup:  ## Setup the development environment.
+	poetry install
+
+.PHONY: readme
+readme:  ## Regenerate README.md.
+	poetry run ./scripts/gen-readme-data.py | \
+		poetry run jinja2 --strict -o README.md --format=json scripts/templates/README.md -
+
+.PHONY: test
+test: clean-tests  ## Run the tests using pytest.
+	poetry run pytest -n auto -k "$(K)" 2>/dev/null
+	-poetry run coverage html --rcfile=coverage.ini

README.md

@@ -0,0 +1 @@
+# mkdocstrings

coverage.ini

@@ -0,0 +1,25 @@
+[coverage:paths]
+source =
+  src/mkdocstrings
+  */site-packages/mkdocstrings
+
+[coverage:run]
+branch = true
+source =
+  mkdocstrings
+  tests
+parallel = true
+
+[coverage:report]
+precision = 2
+omit =
+  src/mkdocstrings/__init__.py
+  src/mkdocstrings/__main__.py
+  tests/*
+
+[coverage:html]
+directory = build/coverage
+extra_css = scripts/templates/coverage.css
+
+[coverage:json]
+output = build/coverage.json

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/code_of_conduct.md

@@ -0,0 +1 @@
+../CODE_OF_CONDUCT.md