Skip to content

Commit d5b614e

Browse files
NusnusNusnus
authored
Documentation Engine Enhancements (#165)
* Added initial glossary * Added make apidoc to docs Makefile (make -C docs apidoc) * Added API reference to doc * Added tox environment to generate API reference in the documentation: tox -e docs-apidoc" * Doc update in src/pytest_celery/__init__.py and src/pytest_celery/plugin.py * Fixed "make -C docs configcheck" * Added docs/_static/ * Fixed "make -C docs apicheck" * Added doc linting check to "tox -e lint" * Add descriptions to testenv commands in tox.ini * Fixed bug with docs/Makefile apidoc * Initial docs/getting-started/introduction.rst * Fixed linter workflow to use tox -e lint (to CI check doc linting)
1 parent 0b33c28 commit d5b614e

26 files changed

+697
-51
lines changed

‎.github/workflows/linter.yml‎

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,19 @@ name: Linter
33
on: [pull_request]
44

55
jobs:
6-
linter:
6+
check:
7+
name: ${{ matrix.check }} check
78
runs-on: ubuntu-latest
9+
strategy:
10+
matrix:
11+
check: [lint, mypy]
812
steps:
9-
10-
- name: Checkout branch
11-
uses: actions/checkout@v4
12-
13-
- name: Run pre-commit
14-
uses: pre-commit/[email protected]
15-
16-
mypy:
17-
runs-on: ubuntu-latest
18-
steps:
19-
2013
- name: Checkout branch
2114
uses: actions/checkout@v4
2215

2316
- name: Install apt packages
2417
run: |
2518
sudo apt update
26-
sudo apt install -y libmemcached-dev
2719
2820
- name: Set up Python 3.12
2921
uses: actions/setup-python@v5
@@ -38,8 +30,8 @@ jobs:
3830
- name: Install Poetry
3931
uses: snok/[email protected]
4032

41-
- name: Install tox and mypy
42-
run: poetry install --with ci
33+
- name: Install CI dependencies
34+
run: poetry install --only ci
4335

44-
- name: Run mypy
45-
run: tox -e mypy
36+
- name: Run check
37+
run: tox -e ${{ matrix.check }}

‎docs/Makefile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ help:
4343
@echo " coverage to run coverage check of the documentation (if enabled)"
4444
@echo " apicheck to verify that all modules are present in autodoc"
4545
@echo " configcheck to verify that all modules are present in autodoc"
46+
@echo " apidoc to regenerate API documentation with sphinx-apidoc"
4647

4748
.PHONY: clean
4849
clean:
@@ -202,3 +203,15 @@ pseudoxml:
202203
.PHONY: livehtml
203204
livehtml:
204205
sphinx-autobuild -b html --host 0.0.0.0 --port 7010 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html
206+
207+
.PHONY: apidoc
208+
apidoc:
209+
# Remove the existing reference directory
210+
@rm -rf $(SOURCEDIR)/reference
211+
# Generate new .rst files with sphinx-apidoc
212+
@sphinx-apidoc -o $(SOURCEDIR)/reference $(SOURCEDIR)/../src -H "API Documentation"
213+
# Rename modules.rst to index.rst
214+
@mv $(SOURCEDIR)/reference/modules.rst $(SOURCEDIR)/reference/index.rst
215+
# Add the .. _apiref: line to the beginning of index.rst
216+
@echo ".. _apiref:\n\n$$(cat $(SOURCEDIR)/reference/index.rst)" > $(SOURCEDIR)/reference/index.rst
217+
@echo "API documentation regenerated."

‎docs/_static/.keep‎

Whitespace-only changes.

‎docs/conf.py‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
conf.build_config(
55
"pytest_celery",
66
__file__,
7-
project="Pytest Celery",
7+
project="pytest_celery",
88
version_dev="1.1",
99
version_stable="1.0",
1010
canonical_url="https://pytest-celery.readthedocs.io/",
@@ -23,7 +23,20 @@
2323
"celery.contrib.sphinx",
2424
],
2525
apicheck_ignore_modules=[
26-
"celery.contrib",
26+
r"celery.contrib.*",
2727
],
28+
linkcheck_ignore=[r"^http://localhost"],
29+
autodoc_mock_imports=[],
2830
)
2931
)
32+
33+
settings = {}
34+
ignored_settings = {}
35+
36+
37+
def configcheck_project_settings():
38+
return set(settings)
39+
40+
41+
def configcheck_should_ignore(setting):
42+
return setting in ignored_settings

‎docs/copyright.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _copyright:
2+
13
Copyright
24
=========
35

‎docs/getting-started/introduction.rst‎

Lines changed: 113 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,117 @@
88
:local:
99
:depth: 1
1010

11-
TBD?
12-
====
11+
What's a Pytest Plugin?
12+
=======================
1313

14-
TBD.
14+
TBD
15+
16+
What do I need?
17+
===============
18+
19+
.. sidebar:: Version Requirements
20+
:subtitle: Pytest Celery version 1.0 runs on
21+
22+
- Python ❨3.8, 3.9, 3.10, 3.11, 3.12❩
23+
24+
Latest celery version comes out of the box but it is recommended to use your own version.
25+
26+
Pytest Celery is a project with minimal funding,
27+
so we don't support Microsoft Windows.
28+
Please don't open any issues related to that platform.
29+
30+
TBD
31+
32+
TODO: Comment about pytest-docker-tools dependency
33+
34+
Get Started
35+
===========
36+
37+
Until the documentation is ready, you can check the following locations
38+
for useful information (in order of usefulness):
39+
40+
- CI_ configuration files.
41+
- Examples_ directory.
42+
- Tests_ directory.
43+
- Source_ code.
44+
45+
.. _CI: https://github.com/celery/pytest-celery/tree/main/.github/workflows
46+
.. _Examples: https://github.com/celery/pytest-celery/tree/main/examples
47+
.. _Tests: https://github.com/celery/pytest-celery/tree/main/tests
48+
.. _Source: https://github.com/celery/pytest-celery/tree/main/src/pytest_celery
49+
50+
Pytest Celery is…
51+
=================
52+
53+
.. topic:: \
54+
55+
- **Simple**
56+
57+
See example below:
58+
59+
.. code-block:: python
60+
61+
def test_hello_world(celery_setup):
62+
assert celery_setup.ready()
63+
64+
- **In development**
65+
66+
As you can see, the documentation is under construction.
67+
68+
69+
.. topic:: It supports
70+
71+
.. hlist::
72+
:columns: 2
73+
74+
- **Cool Stuff**
75+
76+
- Highlights.
77+
- More highlights.
78+
79+
- **Celery Stuff**
80+
81+
- Testing infra capabilities.
82+
83+
Features
84+
========
85+
86+
.. topic:: \
87+
88+
.. hlist::
89+
:columns: 2
90+
91+
- **Pytest**
92+
93+
This is a pytest plugin.
94+
95+
:ref:`Read more… <faq>`.
96+
97+
- **Celery**
98+
99+
For Celery.
100+
101+
:ref:`Read more… <faq>`.
102+
103+
Quick Jump
104+
==========
105+
106+
.. topic:: I want to ⟶
107+
108+
.. hlist::
109+
:columns: 2
110+
111+
- :ref:`To read Contributing <contributing>`
112+
- :ref:`To read FAQ <faq>`
113+
- :ref:`To read API Reference <apiref>`
114+
115+
.. topic:: Jump to ⟶
116+
117+
.. hlist::
118+
:columns: 4
119+
120+
- :ref:`Contributing <contributing>`
121+
- :ref:`FAQ <faq>`
122+
- :ref:`API Reference <apiref>`
123+
124+
.. include:: ../includes/installation.txt

‎docs/glossary.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. _glossary:
2+
3+
Glossary
4+
========
5+
6+
.. glossary::
7+
:sorted:
8+
9+
tbd
10+
To be defined.

‎docs/includes/installation.txt‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. _pytest_celery-installation:
2+
3+
Installation
4+
============
5+
6+
You can install Pytest Celery either via the Python Package Index (PyPI).
7+
8+
To install using :command:`pip`:
9+
10+
.. code-block:: console
11+
12+
$ pip install -U pytest-celery
13+
14+
.. _pytest_celery-installing-from-git:
15+
16+
Using the development version
17+
-----------------------------
18+
19+
TBD
20+
21+
With git
22+
~~~~~~~~
23+
24+
Please see the :ref:`Contributing <contributing>` section.

‎docs/index.rst‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
===================================================
2-
pytest-celery - Official pytest plugin for Celery
2+
Pytest Celery - Official pytest plugin for Celery
33
===================================================
44

5+
.. warning::
6+
7+
Documentation under construction!
8+
59
Welcome to pytest-celery, the official pytest plugin for Celery.
610

711
Pytest Celery is Open Source and licensed under the `BSD License`_.
@@ -13,17 +17,16 @@ Donations
1317

1418
This project relies on your generous donations.
1519

16-
If you are using Pytest Celery to test a commercial product, please consider becoming our `backer`_ or our `sponsor`_ to ensure Pytest Celery's future.
20+
If you are using Pytest Celery to test a commercial product, please consider becoming
21+
our `backer`_ or our `sponsor`_ to ensure Pytest Celery's future.
1722

18-
.. _`backer`: https://opencollective.com/celery#backer
19-
.. _`sponsor`: https://opencollective.com/celery#sponsor
23+
.. _`backer`: https://opencollective.com/celery
24+
.. _`sponsor`: https://opencollective.com/celery
2025

2126
Getting Started
2227
===============
2328

24-
- If you're new to Celery you can get started by following
25-
the :ref:`first-steps` tutorial.
26-
29+
- If you're new to pytest-celery you can get started by following the :ref:`getting-started` tutorial.
2730
- You can also check out the :ref:`FAQ <faq>`.
2831

2932
Contents
@@ -34,25 +37,24 @@ Contents
3437

3538
copyright
3639

37-
.. toctree::
38-
:maxdepth: 1
39-
40-
getting-started/index
41-
4240
.. toctree::
4341
:maxdepth: 2
4442

43+
getting-started/index
4544
userguide/index
4645

4746
.. toctree::
4847
:maxdepth: 1
4948

49+
reference/index
50+
contributing
5051
faq
5152
changelog
52-
contributing
53+
glossary
5354

5455
Indices and tables
5556
==================
5657

5758
* :ref:`genindex`
59+
* :ref:`modindex`
5860
* :ref:`search`

‎docs/reference/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _apiref:
2+
3+
API Documentation
4+
=================
5+
6+
.. toctree::
7+
:maxdepth: 4
8+
9+
pytest_celery

0 commit comments

Comments
 (0)