Initial Commit

Signed-off-by: John Andersen <john.s.andersen@intel.com>

Author: John Andersen

.ci/pages.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+python3 -m pip install --prefix=${HOME}/.local/ -e .[dev]
+export PATH="${HOME}/.local/bin:${PATH}"
+sphinx-build -b html docs pages

.gitignore

@@ -0,0 +1,5 @@
+*__pycache__/
+*.swp
+*.pyc
+*.egg-info/
+pages/

README.md

@@ -0,0 +1,50 @@
+# Example Project for Python\*
+
+This is an example repo to show you how to create a Python package which can be
+published on PiPy. It also includes documentation generation and CI scripts you
+can copy.
+
+## Install From Git Repo
+
+```console
+$ python3 -m pip install --user git+https://github.com/intel/project-example-for-python
+```
+
+## Install For Development
+
+```console
+$ git clone https://github.com/intel/project-example-for-python
+$ python3 -m pip install --user -e .[dev]
+```
+
+## Usage
+
+```console
+$ export PATH="${HOME}/.local/bin:${PATH}"
+$ script
+SCRIPT!
+$ scriptscript
+SCRIPTSCRIPT!
+$ ufb
+It's a bird it's a plane!
+NO! It's a SCRIPT!!
+```
+
+## Docs
+
+```console
+$ sphinx-build -b html docs pages
+$ (cd pages && python3 -m http.server 4444)
+```
+
+## Legal
+
+> This software is subject to the U.S. Export Administration Regulations and
+> other U.S. law, and may not be exported or re-exported to certain countries
+> (Cuba, Iran, Crimea Region of Ukraine, North Korea, Sudan, and Syria) or to
+> persons or entities prohibited from receiving U.S. exports (including
+> Denied Parties, Specially Designated Nationals, and entities on the Bureau
+> of Export Administration Entity List or involved with missile technology or
+> nuclear, chemical or biological weapons).
+
+> \*Other names and brands may be claimed as the property of others.

docs/autogenerated.rst

@@ -0,0 +1,13 @@
+Autogenerated Docs
+==================
+
+These docs are autogenerated. Only functions with docstrings will be here! All
+classes get added even if they don't have docstrings.
+
+.. automodule:: example_project_for_python.importable
+   :members:
+   :undoc-members:
+
+.. automodule:: example_project_for_python.aclass
+   :members:
+   :undoc-members:

docs/conf.py

@@ -0,0 +1,71 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+from unittest.mock import patch
+
+# Copy pasting be gone!
+sys.path.insert(0, os.path.abspath(".."))
+
+with patch("setuptools.setup"):
+    from setup import ORG, IMPORT_NAME, DESCRIPTION, VERSION, AUTHOR_NAME
+
+
+# -- Project information -----------------------------------------------------
+
+project = IMPORT_NAME
+copyright = "2019, Intel Corperation"
+author = AUTHOR_NAME
+
+# The short X.Y version
+version = VERSION
+
+# The full version, including alpha/beta/rc tags
+release = VERSION
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.asyncio",
+]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# -- Extension configuration -------------------------------------------------

docs/index.rst

@@ -0,0 +1,25 @@
+Project Example For Python Documentation
+=========================
+
+Here's all the things these docs know about
+
+.. Here's a note, you won't see it rendered
+
+.. The toctree is the main table of contents for this site, don't add the .rst
+   suffix to your entries here
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    autogenerated
+    rst
+
+.. This is a reference, it can help you link sections across docs
+
+.. _feedface:
+
+Hi I'm a subheader
+------------------
+
+This is some text

docs/rst.rst

@@ -0,0 +1,30 @@
+Restructured Text Examples
+==========================
+
+- Yo
+
+  - Yo
+
+    - Yo
+
+- This
+
+  - Is a list
+
+.. With rst you MUST put empty lines between entries in lists
+
+I'm a link to the :doc:`autogenerated` docs page.
+
+I'm a link to the :ref:`feedface` section.
+
+I'm a link to `an awesome open source project <https://intel.github.io/dffml>`_
+
+This is a link to a method :meth:`project_example_for_python.aclass.MiscClass.load`
+
+This is a link to a class :class:`project_example_for_python.importable.SomeClass`
+
+.. code-block:: python
+
+    def im(some):
+      python = "code"
+      when_in.vim("I'm auto highlighted as Python code within the rst file")

project_example_for_python/__init__.py

@@ -0,0 +1,13 @@
+class MiscClass:
+
+    @classmethod
+    def load(cls1):
+        """
+        I heard you like classmethods so I put a classmethod in your
+        classmethod dawg
+        """
+        class MyClass:
+            @classmethod
+            def classception(cls2):
+                return type("NewClass", (cls1, cls2,), {"FEED": "FACE"})
+        return MyClass

project_example_for_python/aclass.py

@@ -0,0 +1,7 @@
+from .importable import outer_script
+
+def SCRIPT():
+    print('SCRIPT!')
+
+def import_SCRIPT():
+    outer_script()

project_example_for_python/cli.py

@@ -0,0 +1,2 @@
+def SCRIPTSCRIPT():
+    print('SCRIPT SCRIPT!')

project_example_for_python/cli_again.py

@@ -0,0 +1,18 @@
+def outer_script():
+    """
+    Are we alone in the universe? Only NASA knows, and if they tell you they
+    have to kill you. I don't make the rules the aliens do.
+
+    >>> scotty.beam(me, "up")
+    """
+    print('It\'s a bird it\'s a plane!')
+    print('NO! It\'s a SCRIPT!!')
+
+
+class SomeClass:
+
+    def hello(self):
+        """
+        This class is useful
+        """
+        return "I swear"

project_example_for_python/importable.py

@@ -0,0 +1,2 @@
+# Example of relative imports
+from ..aclass import MiscClass

project_example_for_python/inner/__init__.py

@@ -0,0 +1,93 @@
+import os
+import sys
+import pathlib
+from setuptools import setup
+
+ORG = "intel"
+NAME = "project-example-for-python"
+DESCRIPTION = "A short desciption of your project"
+VERSION = "1.33.7"
+AUTHOR_NAME = "You Name Here!"
+AUTHOR_EMAIL = "some.body@once.toldme"
+
+SELF_PATH = os.path.dirname(os.path.abspath(__file__))
+
+README = pathlib.Path(SELF_PATH, "README.md").read_text()
+
+# Folders on disk for Python packages must be _ and not -
+IMPORT_NAME = NAME.replace("-", "_")
+
+setup(
+    name=NAME,
+    version=VERSION,
+    description=DESCRIPTION,
+    long_description=README,
+    # long_description_content_type is needed to make non-rst readmes display
+    # correctly in PyPi, if you see a warning saying something like "I don't
+    # know what this means" don't listen to it, it lies, it does know what this
+    # means and if you have a .md README then you need to keep this line.
+    long_description_content_type="text/markdown",
+    author=AUTHOR_NAME,
+    author_email=AUTHOR_EMAIL,
+    url='https://github.com/{}/{}'.format(ORG, NAME),
+    license='MIT',
+
+    keywords=[
+        'this',
+        'is',
+        'where',
+        'searchable',
+        'keywords',
+        'go',
+    ],
+
+    # Your package will fail to upload if you don't abide by these dude!:
+    # https://pypi.org/classifiers/
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: MIT License',
+        'License :: OSI Approved :: Apache Software License',
+        'Natural Language :: English',
+        'Operating System :: OS Independent',
+        # You must list all the version of Python that you want to allow to
+        # download your package here. If you don't list it, users trying to pip
+        # install it won't be able to get it from PyPi
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: Implementation :: CPython',
+        'Programming Language :: Python :: Implementation :: PyPy',
+    ],
+
+    # Dependencies got here aka install_requires=['dffml']
+    install_requires=[],
+    # Dependencies only needed for running your tests go here
+    tests_require=[],
+    # If you include data files in your repo, you probably want the following
+    # two lines
+    include_package_data=True,
+    zip_safe=False,
+    # Install development dependencies with
+    # pip install folder_containing_this_setup_py[dev]
+    extras_require={
+        "dev": [
+            "coverage",
+            "codecov",
+            "sphinx",
+            "sphinxcontrib-asyncio",
+            "black",
+            "sphinx_rtd_theme",
+        ],
+    },
+    # Python's plugin system, console_scripts says make command line utilities
+    # out of these functions, note the `python.path : obj_in_file` syntax.
+    # Don't forget the `:`!
+    entry_points={
+        'console_scripts': [
+            'script = {}.cli:SCRIPT'.format(IMPORT_NAME),
+            'scriptscript = {}.cli_again:SCRIPTSCRIPT'.format(IMPORT_NAME),
+            'ufb = {}.cli:import_SCRIPT'.format(IMPORT_NAME),
+        ],
+    },
+)