Contributing guidelines (#758)

* 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

.gitignore

@@ -70,6 +70,7 @@ target/
 # virtualenv
 venv/
 ENV/
+.venv/
 
 # OS X
 .DS_Store

CONTRIBUTING.rst

@@ -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 git@github.com:<your-username>/pypika.git
+        cd pypika
+        git remote add upstream git@github.com: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.

Makefile

@@ -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)

README.rst

@@ -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
 -------

docs/6_contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst

docs/api/pypika.analytics.rst

@@ -0,0 +1,7 @@
+pypika.analytics module
+=======================
+
+.. automodule:: pypika.analytics
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pypika.dialects.rst

@@ -0,0 +1,7 @@
+pypika.dialects module
+======================
+
+.. automodule:: pypika.dialects
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pypika.pseudocolumns.rst

@@ -0,0 +1,7 @@
+pypika.pseudocolumns module
+===========================
+
+.. automodule:: pypika.pseudocolumns
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pypika.rst

@@ -3,9 +3,11 @@ pypika package
 
 .. toctree::
 
-
+   pypika.analytics
+   pypika.dialects
    pypika.enums
    pypika.functions
+   pypika.pseudocolumns
    pypika.queries
    pypika.terms
    pypika.utils

docs/conf.py

@@ -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.

docs/index.rst

@@ -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
 --------
 
@@ -20,6 +24,7 @@ Contents
     3_advanced
     4_extending
     5_reference
+    6_contributing
 
 Indices and tables
 ------------------

pypika/__init__.py

@@ -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,

pypika/queries.py

@@ -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
@@ -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)
 
@@ -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)
 
@@ -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)
 
@@ -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)
 
@@ -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)
@@ -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)

requirements-dev.txt

@@ -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