Skip to content

Commit

Permalink
Contributing guidelines (#758)
Browse files Browse the repository at this point in the history
* add another common location

* code block but also ticks

* add command to build docs

* switch to rst format

* link to new file

* update the contributing section

* add some more text in the steps

* add missing modules to docs

* pin jinja2 and add support for numpydoc style

* reference numpydoc
  • Loading branch information
wd60622 authored Oct 16, 2023
1 parent ded17eb commit 627b60a
Show file tree
Hide file tree
Showing 14 changed files with 207 additions and 19 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ target/
# virtualenv
venv/
ENV/
.venv/

# OS X
.DS_Store
101 changes: 101 additions & 0 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
Guidelines for Contributing
===========================

PyPika welcomes contributions in all forms. These may be bugs, feature requests, documentation, or examples. Please feel free to:

#. Submitting an issue
#. Opening a pull request
#. Helping with outstanding issues and pull requests

Open an issue
-------------

If you find a bug or have a feature request, please `open an issue <https://github.com/kayak/pypika/issues>`_ on GitHub. Please just check that the issue doesn't already exist before opening a new one.

Local development steps
-----------------------

Create a forked branch of the repo
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Do this once but keep it up to date

#. `Fork the kayak/PyPika repo GitHub <https://github.com/kayak/pypika/fork>`_
#. Clone forked repo and set upstream

.. code-block:: bash
git clone [email protected]:<your-username>/pypika.git
cd pypika
git remote add upstream [email protected]:kayak/pypika.git
Setup local development environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Setup up python virtual environment

Create and activate the environment. Here is an example using ``venv`` from the standard library:

.. code-block:: bash
python -m venv .venv
source .venv/bin/activate
#. Install python dependencies for development

With the virtual environment activated, install the development requirements, pre-commit, and the package itself:

.. code-block:: bash
make install
#. Run the tests

The unit tests are run with ``unittest`` via ``tox``. To run the tests locally:

.. code-block:: bash
make test
These tests will also run on GitHub Actions when you open a pull request.

#. Build the docs locally

Our docs are built with Sphinx. To build the docs locally:

.. code-block:: bash
make docs.build
Open the docs in your browser. For instance, on macOS:

.. code-block:: bash
open docs/_build/index.html
Pull Request checklist
----------------------

Please check that your pull request meets the following criteria:

- Unit tests pass
- pre-commit hooks pass
- Docstring and examples and checking for correct render in the docs

Documentation
-------------

Documentation is built with Sphinx and hosted on `Read the Docs <https://pypika.readthedocs.io/en/latest/>`_. The latest builds are displayed on their site `here <https://readthedocs.org/projects/pypika/builds/>`_.

The code documentation is to be written in the docstrings of the code itself or in the various ``.rst`` files in project root or the ``docs/`` directory.

The docstrings can be in either `Numpy <https://numpydoc.readthedocs.io/en/latest/format.html>`_ or `Sphinx <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_ format.

Automations
-----------

We use `pre-commit <https://pre-commit.com/>`_ to automate format checks. Install the pre-commit hooks with the ``make install`` command described above.

GitHub Actions runs both format checks and unit tests on every pull request.

**NOTE:** The hosted documentation is built separately from the GitHub Actions workflow. To build the docs locally, use the ``make docs.build`` command described above.
23 changes: 23 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SOURCEDIR = docs
BUILDDIR = docs/_build


help: ## Show this help.
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'

install: ## Install development dependencies
pip install -r requirements-dev.txt pre-commit -e .
pre-commit install

test: ## Run tests
tox

docs.build: ## Build the documentation
$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html -E
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)."

docs.clean: ## Remove the generated documentation
rm -rf $(BUILDDIR)
10 changes: 9 additions & 1 deletion README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1370,9 +1370,17 @@ This produces:
.. _tutorial_end:

.. _contributing_start:

.. _license_start:
Contributing
------------

We welcome community contributions to |Brand|. Please see the `contributing guide <6_contributing.html>`_ to more info.

.. _contributing_end:


.. _license_start:

License
-------
Expand Down
1 change: 1 addition & 0 deletions docs/6_contributing.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. include:: ../CONTRIBUTING.rst
7 changes: 7 additions & 0 deletions docs/api/pypika.analytics.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
pypika.analytics module
=======================

.. automodule:: pypika.analytics
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/api/pypika.dialects.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
pypika.dialects module
======================

.. automodule:: pypika.dialects
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/api/pypika.pseudocolumns.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
pypika.pseudocolumns module
===========================

.. automodule:: pypika.pseudocolumns
:members:
:undoc-members:
:show-inheritance:
4 changes: 3 additions & 1 deletion docs/api/pypika.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@ pypika package

.. toctree::


pypika.analytics
pypika.dialects
pypika.enums
pypika.functions
pypika.pseudocolumns
pypika.queries
pypika.terms
pypika.utils
Expand Down
1 change: 1 addition & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
'numpydoc',
]

# Add any paths that contain templates here, relative to this directory.
Expand Down
5 changes: 5 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ PyPika - Python Query Builder
:start-after: _appendix_start:
:end-before: _appendix_end:

.. include:: ../README.rst
:start-after: _contributing_start:
:end-before: _contributing_end:

Contents
--------

Expand All @@ -20,6 +24,7 @@ Contents
3_advanced
4_extending
5_reference
6_contributing

Indices and tables
------------------
Expand Down
36 changes: 25 additions & 11 deletions pypika/__init__.py
Original file line number Diff line number Diff line change
@@ -1,35 +1,49 @@
"""
PyPika is divided into a couple of modules, primarily the ``queries`` and ``terms`` modules.
pypika.queries
--------------
pypika.analytics
----------------
This is where the ``Query`` class can be found which is the core class in PyPika. Also, other top level classes such
as ``Table`` can be found here. ``Query`` is a container that holds all of the ``Term`` types together and also
serializes the builder to a string.
Wrappers for SQL analytic functions
pypika.terms
pypika.dialects
---------------
This contains all of the dialect specific implementations of the ``Query`` class.
pypika.enums
------------
This module contains the classes which represent individual parts of queries that extend the ``Term`` base class.
Enumerated values are kept in this package which are used as options for Queries and Terms.
pypika.functions
----------------
Wrappers for common SQL functions are stored in this package.
pypika.enums
------------
pypika.pseudocolumns
--------------------
Enumerated values are kept in this package which are used as options for Queries and Terms.
Wrappers for common SQL pseudocolumns are stored in this package.
pypika.queries
--------------
This is where the ``Query`` class can be found which is the core class in PyPika. Also, other top level classes such
as ``Table`` can be found here. ``Query`` is a container that holds all of the ``Term`` types together and also
serializes the builder to a string.
pypika.terms
------------
This module contains the classes which represent individual parts of queries that extend the ``Term`` base class.
pypika.utils
------------
This contains all of the utility classes such as exceptions and decorators.
"""

# noinspection PyUnresolvedReferences
from pypika.dialects import (
ClickHouseQuery,
Expand Down
21 changes: 15 additions & 6 deletions pypika/queries.py
Original file line number Diff line number Diff line change
Expand Up @@ -350,6 +350,15 @@ class Query:
pattern.
This class is immutable.
Examples
--------
Simple query
.. code-block:: python
from pypika import Query, Field
q = Query.from_('customers').select('*').where(Field("id") == 1)
"""

@classmethod
Expand All @@ -367,7 +376,7 @@ def from_(cls, table: Union[Selectable, str], **kwargs: Any) -> "QueryBuilder":
An instance of a Table object or a string table name.
:returns QueryBuilder
:return: QueryBuilder
"""
return cls._builder(**kwargs).from_(table)

Expand Down Expand Up @@ -458,7 +467,7 @@ def into(cls, table: Union[Table, str], **kwargs: Any) -> "QueryBuilder":
An instance of a Table object or a string table name.
:returns QueryBuilder
:return QueryBuilder
"""
return cls._builder(**kwargs).into(table)

Expand All @@ -478,7 +487,7 @@ def select(cls, *terms: Union[int, float, str, bool, Term], **kwargs: Any) -> "Q
A list of terms to select. These can be any type of int, float, str, bool, or Term. They cannot be a Field
unless the function ``Query.from_`` is called first.
:returns QueryBuilder
:return: QueryBuilder
"""
return cls._builder(**kwargs).select(*terms)

Expand All @@ -493,7 +502,7 @@ def update(cls, table: Union[str, Table], **kwargs) -> "QueryBuilder":
An instance of a Table object or a string table name.
:returns QueryBuilder
:return: QueryBuilder
"""
return cls._builder(**kwargs).update(table)

Expand All @@ -507,7 +516,7 @@ def Table(cls, table_name: str, **kwargs) -> _TableClass:
A string table name.
:returns Table
:return: Table
"""
kwargs["query_cls"] = cls
return Table(table_name, **kwargs)
Expand All @@ -523,7 +532,7 @@ def Tables(cls, *names: Union[TypedTuple[str, str], str], **kwargs: Any) -> List
A list of string table names, or name and alias tuples.
:returns Table
:return: Table
"""
kwargs["query_cls"] = cls
return make_tables(*names, **kwargs)
Expand Down
2 changes: 2 additions & 0 deletions requirements-dev.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
Sphinx==1.6.5
sphinx-rtd-theme==0.2.4
bumpversion==0.5.3
jinja2==3.0.3
numpydoc==1.1.0

# Testing
parameterized==0.7.0
Expand Down

0 comments on commit 627b60a

Please sign in to comment.