Skip to content

Commit fe6faa5

Browse files
oprypinpawamoy
oprypin
and
pawamoy
committed
feat: Split out "mkdocs-autorefs" plugin from "mkdocstrings"
Directly based on https://github.com/mkdocstrings/mkdocstrings/tree/60b8b698d070a5aab8296d9a472575c17860edd2 Co-authored-by: Timothée Mazzucotelli <pawamoy@pm.me>
0 parents  commit fe6faa5

24 files changed

Lines changed: 1535 additions & 0 deletions

‎.github/FUNDING.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
github:
2+
- pawamoy
3+
ko_fi: pawamoy
4+
liberapay: pawamoy
5+
patreon: pawamoy
6+
custom:
7+
- https://www.paypal.me/pawamoy

‎.github/workflows/ci.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: ci
2+
3+
on:
4+
push:
5+
pull_request:
6+
branches:
7+
- master
8+
9+
defaults:
10+
run:
11+
shell: bash
12+
13+
env:
14+
LANG: "en_US.utf-8"
15+
LC_ALL: "en_US.utf-8"
16+
POETRY_VIRTUALENVS_IN_PROJECT: "true"
17+
PYTHONIOENCODING: "UTF-8"
18+
PYTHONPATH: docs
19+
20+
jobs:
21+
22+
quality:
23+
24+
runs-on: ubuntu-latest
25+
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v2
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v2
32+
with:
33+
python-version: 3.8
34+
35+
- name: Set up the cache
36+
uses: actions/cache@v1
37+
with:
38+
path: .venv
39+
key: quality-venv-cache-2
40+
41+
- name: Set up the project
42+
run: |
43+
pip install poetry
44+
poetry install -v || { rm -rf .venv; poetry install -v; }
45+
poetry update
46+
47+
- name: Check if the documentation builds correctly
48+
run: poetry run duty check-docs
49+
50+
- name: Check the code quality
51+
run: poetry run duty check-code-quality
52+
53+
- name: Check if the code is correctly typed
54+
run: poetry run duty check-types
55+
56+
- name: Check for vulnerabilities in dependencies
57+
run: |
58+
pip install safety
59+
poetry run duty check-dependencies
60+
61+
tests:
62+
63+
strategy:
64+
matrix:
65+
os: [ubuntu-latest, macos-latest, windows-latest]
66+
python-version: [3.6, 3.7, 3.8, 3.9]
67+
68+
runs-on: ${{ matrix.os }}
69+
70+
steps:
71+
- name: Checkout
72+
uses: actions/checkout@v2
73+
74+
- name: Set up Python ${{ matrix.python-version }}
75+
uses: actions/setup-python@v2
76+
with:
77+
python-version: ${{ matrix.python-version }}
78+
79+
- name: Set up the cache
80+
uses: actions/cache@v1
81+
with:
82+
path: .venv
83+
key: tests-venv-cache-${{ matrix.os }}-py${{ matrix.python-version }}
84+
85+
- name: Set up the project
86+
run: |
87+
pip install poetry
88+
poetry install -v || { rm -rf .venv; poetry install -v; }
89+
poetry update
90+
91+
- name: Run the test suite
92+
run: poetry run duty test

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.idea/
2+
__pycache__/
3+
*.py[cod]
4+
dist/
5+
*.egg-info/
6+
build/
7+
.coverage*
8+
pip-wheel-metadata/
9+
.pytest_cache/
10+
.python-version
11+
site/
12+
poetry.lock
13+
.mypy_cache/
14+
.venv/

‎CODE_OF_CONDUCT.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at pawamoy@pm.me. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at [http://contributor-covenant.org/version/1/4][version]
72+
73+
[homepage]: http://contributor-covenant.org
74+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Contributing
2+
3+
Contributions are welcome, and they are greatly appreciated!
4+
Every little bit helps, and credit will always be given.
5+
6+
## Environment setup
7+
8+
Nothing easier!
9+
10+
Fork and clone the repository, then:
11+
12+
```bash
13+
cd mkdocs-autorefs
14+
make setup
15+
```
16+
17+
!!! note
18+
If it fails for some reason,
19+
you'll need to install
20+
[Poetry](https://github.com/python-poetry/poetry)
21+
manually.
22+
23+
You can install it with:
24+
25+
```bash
26+
python3 -m pip install --user pipx
27+
pipx install poetry
28+
```
29+
30+
Now you can try running `make setup` again,
31+
or simply `poetry install`.
32+
33+
You now have the dependencies installed.
34+
35+
Run `make help` to see all the available actions!
36+
37+
## Tasks
38+
39+
This project uses [duty](https://github.com/pawamoy/duty) to run tasks.
40+
A Makefile is also provided. The Makefile will try to run certain tasks
41+
on multiple Python versions. If for some reason you don't want to run the task
42+
on multiple Python versions, you can do one of the following:
43+
44+
1. `export PYTHON_VERSIONS= `: this will run the task
45+
with only the current Python version
46+
2. run the task directly with `poetry run duty TASK`,
47+
or `duty TASK` if the environment was already activated
48+
through `poetry shell`
49+
50+
The Makefile detects if the Poetry environment is activated,
51+
so `make` will work the same with the virtualenv activated or not.
52+
53+
## Development
54+
55+
As usual:
56+
57+
1. create a new branch: `git checkout -b feature-or-bugfix-name`
58+
1. edit the code and/or the documentation
59+
60+
If you updated the documentation or the project dependencies:
61+
62+
1. run `make docs-regen`
63+
1. run `make docs-serve`,
64+
go to http://localhost:8000 and check that everything looks good
65+
66+
**Before committing:**
67+
68+
1. run `make format` to auto-format the code
69+
1. run `make check` to check everything (fix any warning)
70+
1. run `make test` to run the tests (fix any issue)
71+
1. follow our [commit message convention](#commit-message-convention)
72+
73+
If you are unsure about how to fix or ignore a warning,
74+
just let the continuous integration fail,
75+
and we will help you during review.
76+
77+
Don't bother updating the changelog, we will take care of this.
78+
79+
## Commit message convention
80+
81+
Commits messages must follow the
82+
[Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message):
83+
84+
```
85+
<type>[(scope)]: Subject
86+
87+
[Body]
88+
```
89+
90+
Scope and body are optional. Type can be:
91+
92+
- `build`: About packaging, building wheels, etc.
93+
- `chore`: About packaging or repo/files management.
94+
- `ci`: About Continuous Integration.
95+
- `docs`: About documentation.
96+
- `feat`: New feature.
97+
- `fix`: Bug fix.
98+
- `perf`: About performance.
99+
- `refactor`: Changes which are not features nor bug fixes.
100+
- `style`: A change in code style/format.
101+
- `tests`: About tests.
102+
103+
**Subject (and body) must be valid Markdown.**
104+
If you write a body, please add issues references at the end:
105+
106+
```
107+
Body.
108+
109+
References: #10, #11.
110+
Fixes #15.
111+
```
112+
113+
## Pull requests guidelines
114+
115+
Link to any related issue in the Pull Request message.
116+
117+
During review, we recommend using fixups:
118+
119+
```bash
120+
# SHA is the SHA of the commit you want to fix
121+
git commit --fixup=SHA
122+
```
123+
124+
Once all the changes are approved, you can squash your commits:
125+
126+
```bash
127+
git rebase -i --autosquash master
128+
```
129+
130+
And force-push:
131+
132+
```bash
133+
git push -f
134+
```
135+
136+
If this seems all too complicated, you can push or force-push each new commit,
137+
and we will squash them ourselves if needed, before merging.

‎LICENSE‎

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

‎Makefile‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.DEFAULT_GOAL := help
2+
SHELL := bash
3+
4+
DUTY = $(shell [ -n "${VIRTUAL_ENV}" ] || echo poetry run) duty
5+
6+
args = $(foreach a,$($(subst -,_,$1)_args),$(if $(value $a),$a="$($a)"))
7+
check_code_quality_args = files
8+
docs_serve_args = host port
9+
release_args = version
10+
test_args = cleancov match
11+
12+
BASIC_DUTIES = \
13+
changelog \
14+
clean \
15+
coverage \
16+
docs \
17+
docs-deploy \
18+
docs-regen \
19+
docs-serve \
20+
format \
21+
release
22+
23+
QUALITY_DUTIES = \
24+
check \
25+
check-code-quality \
26+
check-dependencies \
27+
check-docs \
28+
check-types \
29+
test
30+
31+
.PHONY: help
32+
help:
33+
@$(DUTY) --list
34+
35+
.PHONY: setup
36+
setup:
37+
@bash scripts/setup.sh
38+
39+
.PHONY: $(BASIC_DUTIES)
40+
$(BASIC_DUTIES):
41+
@$(DUTY) $@ $(call args,$@)
42+
43+
.PHONY: $(QUALITY_DUTIES)
44+
$(QUALITY_DUTIES):
45+
@bash scripts/multirun.sh duty $@ $(call args,$@)

0 commit comments

Comments
 (0)