pytask-dev · tobiasraabe · Apr 14, 2022 · Apr 13, 2022 · Apr 13, 2022 · Apr 13, 2022
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -28,9 +28,6 @@ repos:
     -   id: python-no-eval
     -   id: python-no-log-warn
     -   id: python-use-type-annotations
-    -   id: rst-backticks
-    -   id: rst-directive-colons
-    -   id: rst-inline-touching-normal
     -   id: text-unicode-replacement-char
 -   repo: https://github.com/asottile/pyupgrade
     rev: v2.32.0
@@ -45,11 +42,6 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
--   repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
-    hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black]
 -   repo: https://github.com/PyCQA/flake8
     rev: 4.0.1
     hooks:
@@ -70,10 +62,6 @@ repos:
             pydocstyle,
             Pygments,
         ]
--   repo: https://github.com/PyCQA/doc8
-    rev: 0.11.1
-    hooks:
-    -   id: doc8
 -   repo: https://github.com/econchick/interrogate
     rev: 1.5.0
     hooks:
@@ -86,6 +74,31 @@ repos:
             "{{cookiecutter.project_slug}}"
         ]
         pass_filenames: false
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-gfm,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (README\.md)
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-myst,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (docs/.)
+        # Exclude files with admonitions.
+        # exclude: |
+        #     (?x)^(
+        #         path/to/file.py
+        #     )$
 -   repo: https://github.com/codespell-project/codespell
     rev: v2.1.0
     hooks:

diff --git a/README.md b/README.md
@@ -0,0 +1,83 @@
+# cookiecutter-pytask-project
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+This repository contains a minimal cookiecutter template for a project with
+[pytask](https://github.com/pytask-dev/pytask).
+
+## Usage
+
+First, install cookiecutter.
+
+```console
+$ pip install cookiecutter
+
+$ conda install -c conda-forge cookiecutter
+```
+
+Then, set up the template with
+
+```console
+$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
+```
+
+## Documentation
+
+If you are new to pytask, just follow the
+[tutorials](https://pytask-dev.readthedocs.io/en/stable/tutorials/index.html) which will
+help you with your first steps like how to write the first task.
+
+If you are already familiar with pytask, the
+[how-to guides](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/index.html)
+offer more in-depth guidance on complex projects.
+
+In general, you will find most guidance in the
+[documentation](https://pytask-dev.readthedocs.io/en/stable/index.html) and some advice
+in the FAQ below.
+
+## FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
+
+Q: My project is a Python package, but it does not seem to have a version. Where is it?
+
+A: The cookiecutter uses [setuptools_scm](https://github.com/pypa/setuptools_scm/) to
+manage the version number. When you install your created project as a Python package
+with `pip install -e .`, setuptools_scm tries to infer the version number from the tags
+created on the repo.
+
+For example, if you have switched to a commit associated with the tag `v0.2.0`,
+setuptools_scm will create a `src/<package_slug>/_version.py` with a variable containing
+`version = '0.2.0'` which you can use in your `src/<package_slug>/__init__.py`. If you
+are one commit ahead of the tag, you version will be something like `0.2.0.dev1+...`
+indicating you are one commit ahead of the tag `v0.2.0`.
+
+If you want to switch to the tradition setup, replace the following code in your
+`pyproject.toml`
+
+```toml
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]
+```
+
+with
+
+```toml
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+```
diff --git a/README.rst b/README.rst
diff --git a/docs/rtd_environment.yml b/docs/rtd_environment.yml
@@ -12,10 +12,12 @@ dependencies:
   - furo
   - ipython
   - nbsphinx
+  - myst-parser
   - sphinx
   - sphinx-autoapi
   - sphinx-copybutton
   - sphinx-panels
 
   - pip:
-    - -e ../
+    - ../
+    - sphinxext-opengraph
diff --git a/docs/source/api.rst → docs/source/api.md b/docs/source/api.rst → docs/source/api.md
@@ -1,11 +1,12 @@
-API Reference
-=============
+# API Reference
 
 The following documents are auto-generated and not carefully edited. They provide direct
 access to the source code and the docstrings.
 
-.. toctree::
-   :titlesonly:
-
-   /autoapi/pre_gen_project/index
-   /autoapi/post_gen_project/index
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/pre_gen_project/index
+/autoapi/post_gen_project/index
+```
diff --git a/docs/source/changes.md b/docs/source/changes.md
@@ -0,0 +1,27 @@
+# Changes
+
+This is a record of all past cookiecutter-pytask-project releases and what went into
+them in reverse chronological order.
+
+## 1.2.0 - 2022-xx-xx
+
+- {pull}`7` skips concurrent CI builds.
+- {pull}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
+- {pull}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
+- {pull}`12` removes `LICENSE` from `MANIFEST.in` if no license is selected.
+- {pull}`13` adds a `.gitignore`.
+- {pull}`14` adds a `CITATION`.
+- {pull}`15` cancels concurrent CI jobs.
+- {pull}`18` fixes {issue}`17` and moves rst to markdown.
+
+## 1.1.0 - 2022-01-16
+
+- {pull}`4` renames the cookiecutter from cookiecutter-pytask to
+  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
+  remove unnecessary packaging stuff.
+
+## 1.0.0 - 2022-01-05
+
+- {pull}`1` creates first release of a minimal cookiecutter template for a pytask
+  project.
+- {pull}`2` adds more tests.
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,10 +32,12 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinxext.opengraph",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "sphinx_panels",
     "autoapi.extension",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -57,9 +59,12 @@
 copybutton_prompt_is_regexp = True
 
 # Use these roles to create links to github users and pull requests.
+_repo = "https://github.com/pytask-dev/cookiecutter-pytask-project"
 extlinks = {
-    "ghuser": ("https://github.com/%s", "@"),
-    "gh": ("https://github.com/pytask-dev/cookiecutter-pytask-project/pull/%s", "#"),
+    "pypi": ("https://pypi.org/project/%s/", ""),
+    "issue": (f"{_repo}/issues/%s", "issue #"),
+    "pull": (f"{_repo}/pull/%s", "pull request #"),
+    "user": ("https://github.com/%s", "@"),
 }
 
 # Link objects to other documentations.
@@ -68,6 +73,9 @@
     "pytask": ("https://pytask-dev.readthedocs.io/en/stable/", None),
 }
 
+# MyST
+myst_enable_extensions = []
+
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/source/faq.md b/docs/source/faq.md
@@ -0,0 +1,41 @@
+# FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
+
+Q: My project is a Python package, but it does not seem to have a version. Where is it?
+
+A: The cookiecutter uses [setuptools_scm](https://github.com/pypa/setuptools_scm/) to
+manage the version number. When you install your created project as a Python package
+with `pip install -e .`, setuptools_scm tries to infer the version number from the tags
+created on the repo.
+
+For example, if you have switched to a commit associated with the tag `v0.2.0`,
+setuptools_scm will create a `src/<package_slug>/_version.py` with a variable containing
+`version = '0.2.0'` which you can use in your `src/<package_slug>/__init__.py`. If you
+are one commit ahead of the tag, you version will be something like `0.2.0.dev1+...`
+indicating you are one commit ahead of the tag `v0.2.0`.
+
+If you want to switch to the tradition setup, replace the following code in your
+`pyproject.toml`
+
+```toml
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]
+```
+
+with
+
+```toml
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+```