Skip to content

Commit ea74db5

Browse files
d3rkyd3rky
authored
Merge pull request #6 from cloudblue/sphinx_docs
Sphinx documentation
2 parents fe10fd1 + d44cc69 commit ea74db5

19 files changed

+1095
-7
lines changed

‎.devcontainer/Dockerfile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#-------------------------------------------------------------------------------------------------------------
2+
# Copyright (c) Microsoft Corporation. All rights reserved.
3+
# Licensed under the MIT License. See https://go.microsoft.com/fwlink/?linkid=2090316 for license information.
4+
#-------------------------------------------------------------------------------------------------------------
5+
6+
# Update the VARIANT arg in devcontainer.json to pick a Python version: 3, 3.8, 3.7, 3.6
7+
# To fully customize the contents of this image, use the following Dockerfile instead:
8+
# https://github.com/microsoft/vscode-dev-containers/tree/v0.128.0/containers/python-3/.devcontainer/base.Dockerfile
9+
ARG VARIANT="3"
10+
FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}
11+
12+
COPY ./requirements /app/requirements
13+
14+
RUN pip install -r /app/requirements/docs.txt
15+
16+
# [Optional] If your requirements rarely change, uncomment this section to add them to the image.
17+
#
18+
# COPY requirements.txt /tmp/pip-tmp/
19+
# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
20+
# && rm -rf /tmp/pip-tmp
21+
22+
# [Optional] Uncomment this section to install additional packages.
23+
#
24+
# RUN apt-get update \
25+
# && export DEBIAN_FRONTEND=noninteractive \
26+
# && apt-get -y install --no-install-recommends <your-package-list-here>
27+

‎.devcontainer/devcontainer.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
// For format details, see https://aka.ms/vscode-remote/devcontainer.json or this file's README at:
2+
// https://github.com/microsoft/vscode-dev-containers/tree/v0.128.0/containers/python-3
3+
{
4+
"name": "Python 3",
5+
"build": {
6+
"dockerfile": "Dockerfile",
7+
"context": "..",
8+
// Update 'VARIANT' to pick a Python version. Rebuild the container
9+
// if it already exists to update. Available variants: 3, 3.6, 3.7, 3.8
10+
"args": { "VARIANT": "3" }
11+
},
12+
13+
// Set *default* container specific settings.json values on container create.
14+
"settings": {
15+
"terminal.integrated.shell.linux": null,
16+
"python.pythonPath": "/usr/local/bin/python",
17+
"python.linting.enabled": true,
18+
"python.linting.pylintEnabled": false,
19+
"python.linting.flake8Enabled": true,
20+
"python.linting.flake8Path": "/usr/local/bin/flake8",
21+
"python.linting.flake8Args": ["--config=setup.cfg"],
22+
"autoDocstring.docstringFormat": "sphinx",
23+
"autoDocstring.startOnNewLine": true
24+
},
25+
26+
// Add the IDs of extensions you want installed when the container is created.
27+
"extensions": [
28+
"ms-python.python",
29+
"njpwerner.autodocstring"
30+
]
31+
32+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
33+
// "forwardPorts": [],
34+
35+
// Use 'postCreateCommand' to run commands after the container is created.
36+
// "postCreateCommand": "pip3 install --user -r requirements.txt",
37+
38+
// Uncomment to connect as a non-root user. See https://aka.ms/vscode-remote/containers/non-root.
39+
// "remoteUser": "vscode"
40+
}

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@ dist/
1212

1313
tests/reports/
1414
.coverage
15+
16+
docs/_build

‎README.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
Django RQL
22
==========
3-
![pyversions](https://img.shields.io/pypi/pyversions/django-rql.svg) [![PyPi Status](https://img.shields.io/pypi/v/django-rql.svg)](https://pypi.org/project/django-rql/) [![codecov](https://codecov.io/gh/cloudblue/django-rql/branch/master/graph/badge.svg)](https://codecov.io/gh/cloudblue/django-rql) [![Build Status](https://travis-ci.org/cloudblue/django-rql.svg?branch=master)](https://travis-ci.org/cloudblue/django-rql) [![PyPI status](https://img.shields.io/pypi/status/django-rql.svg)](https://pypi.python.org/pypi/django-rql/) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=django-rql&metric=alert_status)](https://sonarcloud.io/dashboard?id=django-rql)
3+
![pyversions](https://img.shields.io/pypi/pyversions/django-rql.svg) [![PyPi Status](https://img.shields.io/pypi/v/django-rql.svg)](https://pypi.org/project/django-rql/) [![Docs](https://readthedocs.org/projects/django-rql/badge/?version=latest)](https://readthedocs.org/projects/django-rql) [![codecov](https://codecov.io/gh/cloudblue/django-rql/branch/master/graph/badge.svg)](https://codecov.io/gh/cloudblue/django-rql) [![Build Status](https://travis-ci.org/cloudblue/django-rql.svg?branch=master)](https://travis-ci.org/cloudblue/django-rql) [![PyPI status](https://img.shields.io/pypi/status/django-rql.svg)](https://pypi.python.org/pypi/django-rql/) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=django-rql&metric=alert_status)](https://sonarcloud.io/dashboard?id=django-rql)
4+
45

56
`django-rql` is an Django application, that implements RQL filter backend for your web application.
67

@@ -32,9 +33,10 @@ Currently supported operators
3233
0. Select (select)
3334

3435

35-
Quickstart
36-
==========
37-
Try to enrich your API filtering opportunities learning [Quickstart Guide][quickstart]
36+
Documentation
37+
=============
38+
39+
Full documentation is available at [https://django-rql.readthedocs.org](https://django-rql.readthedocs.org).
3840

3941

4042
Example
@@ -194,7 +196,7 @@ Development
194196
===========
195197

196198
1. Python 3.5+
197-
0. Install dependencies `requirements/dev.txt`
199+
0. Install dependencies `requirements/dev.txt` and `requirements/extra.txt`
198200

199201
Testing
200202
=======
@@ -213,4 +215,3 @@ Tests reports are generated in `tests/reports`.
213215
To generate HTML coverage reports use:
214216
`--cov-report html:tests/reports/cov_html`
215217

216-
[quickstart]: ./docs/quickstart.md

‎dj_rql/constants.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,32 +45,74 @@
4545

4646
class FilterLookups:
4747
EQ = 'eq'
48+
"""`Equal` operator"""
49+
4850
NE = 'ne'
51+
"""`Not equal` operator"""
52+
4953
GE = 'ge'
54+
"""`Greater or equal` operator"""
55+
5056
GT = 'gt'
57+
"""`Greater than` operator"""
58+
5159
LE = 'le'
60+
"""`Less or equal` operator"""
61+
5262
LT = 'lt'
63+
"""`Less then` operator"""
5364

5465
IN = 'in'
66+
"""`In` operator"""
67+
5568
OUT = 'out'
69+
"""`Not in` operator"""
5670

5771
NULL = 'null'
72+
"""`null` operator"""
5873

5974
LIKE = 'like'
75+
"""`like` operator"""
76+
6077
I_LIKE = 'ilike'
78+
"""`Case-insensitive like` operator"""
6179

6280
@classmethod
6381
def numeric(cls, with_null=True):
82+
"""
83+
Returns the default lookups for numeric fields.
84+
85+
:param with_null: if true, includes the `null` lookup, defaults to True
86+
:type with_null: bool, optional
87+
:return: a set with the default lookups.
88+
:rtype: set
89+
"""
6490
return cls._add_null(
6591
{cls.EQ, cls.NE, cls.GE, cls.GT, cls.LT, cls.LE, cls.IN, cls.OUT}, with_null,
6692
)
6793

6894
@classmethod
6995
def string(cls, with_null=True):
96+
"""
97+
Returns the default lookups for string fields.
98+
99+
:param with_null: if true, includes the `null` lookup, defaults to True
100+
:type with_null: bool, optional
101+
:return: a set with the default lookups.
102+
:rtype: set
103+
"""
70104
return cls._add_null({cls.EQ, cls.NE, cls.IN, cls.OUT, cls.LIKE, cls.I_LIKE}, with_null)
71105

72106
@classmethod
73107
def boolean(cls, with_null=True):
108+
"""
109+
Returns the default lookups for boolean fields.
110+
111+
:param with_null: if true, includes the `null` lookup, defaults to True
112+
:type with_null: bool, optional
113+
:return: a set with the default lookups.
114+
:rtype: set
115+
"""
74116
return cls._add_null({cls.EQ, cls.NE}, with_null)
75117

76118
@classmethod

‎dj_rql/filter_cls.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,24 @@
3939

4040

4141
class RQLFilterClass:
42+
"""Base class for filter classes."""
43+
4244
MODEL = None
45+
"""The model this filter is for."""
46+
4347
FILTERS = None
48+
"""A list or tuple of filters definitions."""
49+
4450
EXTENDED_SEARCH_ORM_ROUTES = tuple()
51+
4552
DISTINCT = False
53+
"""If True, a `SELECT DISTINCT` will always be executed."""
54+
4655
SELECT = False
56+
"""If True, this FilterClass supports the ``select`` operator."""
57+
4758
OPENAPI_SPECIFICATION = RQLFilterClassSpecification
59+
"""Class for OpenAPI specifications generation."""
4860

4961
def __init__(self, queryset, instance=None):
5062
self.queryset = queryset

‎dj_rql/qs.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,13 @@ def apply(self, queryset):
4545

4646

4747
class SelectRelated(DBOptimization):
48+
"""Apply a ``select_related`` optimization to the queryset."""
4849
def apply(self, queryset):
4950
return queryset.select_related(*self._relations)
5051

5152

5253
class PrefetchRelated(DBOptimization):
54+
"""Apply a ``prefetch_related`` optimization to the queryset."""
5355
def apply(self, queryset):
5456
return queryset.prefetch_related(*self._relations)
5557

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import os
2+
import sys
3+
from datetime import datetime
4+
5+
from setuptools_scm import get_version
6+
7+
import django
8+
9+
10+
sys.path.insert(0, os.path.abspath('..'))
11+
os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.dj_rf.settings'
12+
django.setup()
13+
14+
15+
# -- Project information -----------------------------------------------------
16+
17+
project = 'django-rql'
18+
copyright = '{}, CloudBlue Inc.'.format(datetime.now().year)
19+
author = 'CloudBlue'
20+
21+
# The full version, including alpha/beta/rc tags
22+
release = get_version(root='..', relative_to=__file__)
23+
24+
25+
# -- General configuration ---------------------------------------------------
26+
27+
# Add any Sphinx extension module names here, as strings. They can be
28+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
29+
# ones.
30+
extensions = [
31+
'sphinx.ext.autodoc',
32+
'sphinx.ext.autosectionlabel',
33+
'sphinx_copybutton',
34+
]
35+
36+
autosectionlabel_prefix_document = True
37+
autodoc_member_order = 'bysource'
38+
39+
# Add any paths that contain templates here, relative to this directory.
40+
templates_path = ['_templates']
41+
42+
# List of patterns, relative to source directory, that match files and
43+
# directories to ignore when looking for source files.
44+
# This pattern also affects html_static_path and html_extra_path.
45+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
46+
47+
48+
# -- Options for HTML output -------------------------------------------------
49+
50+
# The theme to use for HTML and HTML Help pages. See the documentation for
51+
# a list of builtin themes.
52+
#
53+
html_theme = 'sphinx_rtd_theme'
54+
55+
# Add any paths that contain custom static files (such as style sheets) here,
56+
# relative to this directory. They are copied after the builtin static files,
57+
# so a file named "default.css" will overwrite the builtin "default.css".
58+
html_static_path = ['_static']

0 commit comments

Comments
 (0)