Merge pull request #31 from seapagan/custom-files

Implement custom template additions

.pre-commit-config.yaml

@@ -48,22 +48,19 @@ repos:
     rev: v2.3.2
     hooks:
       - id: tryceratops
-
-  # the below is currently disabled since there seems to be a conflict with
-  # 'typing-extensions' versions.
-  # - repo: https://github.com/python-poetry/poetry
-  #   rev: "1.5.0"
-  #   hooks:
-  #     - id: poetry-check
-  #     # - id: poetry-lock
-  #     - id: poetry-export
-  #       args:
-  #         [
-  #           "--without-hashes",
-  #           "-f",
-  #           "requirements.txt",
-  #           "-o",
-  #           "requirements.txt",
-  #           "--with",
-  #           "dev",
-  #         ]
+  - repo: https://github.com/python-poetry/poetry
+    rev: "1.5.0"
+    hooks:
+      - id: poetry-check
+      # - id: poetry-lock
+      - id: poetry-export
+        args:
+          [
+            "--without-hashes",
+            "-f",
+            "requirements.txt",
+            "-o",
+            "requirements.txt",
+            "--with",
+            "dev",
+          ]

.vscode/settings.json

@@ -39,7 +39,11 @@
   "python.linting.flake8Enabled": true,
   "python.linting.mypyEnabled": true,
   "python.linting.pydocstyleArgs": ["--convention=google"],
-  "python.linting.pylintArgs": [],
+  "python.linting.pylintArgs": [
+    "--load-plugins",
+    "pylint_pydantic",
+    "pylint-pytest"
+  ],
   "python.linting.pylintEnabled": false,
   "python.pythonPath": "./.venv/bin/python",
   "isort.args": ["--profile", "black", "--src=${workspaceFolder}"],

README.md

@@ -16,6 +16,7 @@ More functionality will be added very shortly and the code will be refactored
 and cleaned up.
 
 - [Installation](#installation)
+- [Documentation](#documentation)
 - [Usage](#usage)
   - [Task Runner](#task-runner)
   - [Customise](#customise)
@@ -47,6 +48,11 @@ or use [pipx](https://pypa.github.io/pipx/)
 $ pipx install pyproject-maker
 ```
 
+## Documentation
+
+Full documentation for this project with usage examples is available at
+<https://py-maker.seapagan.net/>
+
 ## Usage
 
 To create a new project, run the following command:

TODO.md

@@ -1,6 +1,6 @@
 # TODO List
 
-- Add testing with [Pytest](https://pytest.org)
+- Add testing with [Pytest](https://pytest.org) (`IN PROGRESS`)
 - Add option to generate a skeleton MkDocs website for the new project
 - Ask for more settings ie homepage, repo, etc. and add them to the generated
   `pyproject.toml` file (if the new project is likely to be uploaded to PyPI)
@@ -13,6 +13,18 @@
   is already taken. If it is, either abort or ask the user if they want to
   continue (making clear they will need to rename the package before it can be
   uploaded).
-- option to dump the default template files to a local directory so they can be
-  edited and used as custom templates, optionally dumping to the
-  `~/.pymaker/templates` folder overwriting existing customizations.
+- add some form of 'extra packages' command line option and config setting to
+  automatically add extra packages to the generated `pyproject.toml` file.
+- add cmd line options to specify the project name, author, etc. so the user
+  doesn't have to enter them manually.
+- add a command line option to specify the project type so the user doesn't have
+  to enter it manually. ie `--standalone` or `--package`(latter is default and
+  wouldn't need to be specified).
+- add a command to the CLI template command to show the template files as a
+  tree, marking whether each file/folder is from the internal templates or the
+  user's templates.
+
+## Documentation
+
+- Add usage examples and perhaps a walk-through to the documentation. Maybe
+  with a YouTube video?

docs/future-plans.md

@@ -0,0 +1 @@
+--8<-- "TODO.md"

docs/index.md

@@ -26,6 +26,15 @@ type checking. [isort](https://pycqa.github.io/isort/){:target="_blank"},
 [tyrceratops](https://github.com/guilatrova/tryceratops){:target="_blank"} are
 also installed as standard.
 
+## Customize the generated project
+
+You can add extra or edited files to the generated project by adding them to the
+`~/.pymaker/template` directory.  The files in this directory will be copied
+into the generated project, overwriting any existing files with the same name.
+
+It is also possible to dump the whole template into this folder or the current
+folder so full customization and even removal of files is possible.
+
 ## Pre-commit
 
 The generated project uses [pre-commit](https://pre-commit.com/) to run some

docs/template/internal.md

@@ -0,0 +1,26 @@
+# The Internal Template
+
+By default, the generated application will have a basic template that you can
+use to get started, this template is stored inside the package itself. It will
+contain all you need to get started, including a basic `README.md` file.
+
+The dependency management is handled by
+[Poetry](<https://python-poetry.org/>){:target="_blank"}, and we include a
+`pyproject.toml` file with several useful dependencies:
+
+- [PyTest](https://docs.pytest.org/en/stable/contents.html){:target="_blank"}
+  for testing, along with several useful plugins.
+- The [Black](https://black.readthedocs.io/en/stable/){:target="_blank"}
+  code formatter.
+- The [Flake8](https://flake8.pycqa.org/en/latest/){:target="_blank"} linter,
+  along with a good selection of plugins. It is also set up to use the
+  `pyproject.toml` for it's configuration, and to work nicely with Black.
+- [Pylint](<https://www.pylint.org/>){:target="_blank"} and
+  [Pydocstyle](https://www.pydocstyle.org/en/stable/){:target="_blank"}
+  linters.
+- [MyPy](https://mypy.readthedocs.io/en/stable/){:target="_blank"} for static
+  type checking.
+- [Isort](https://pycqa.github.io/isort/){:target="_blank"} for sorting
+  imports.
+- [pre-commit](https://pre-commit.com/){:target="_blank"} for running checks
+  before committing code.

docs/template/modify.md

@@ -0,0 +1,13 @@
+# Adding or Modifying files in the template
+
+If you wish to add or change specific files in the template, you can do so by
+adding them to the `~/.pymaker/template` folder. The files (and folders) in this
+folder will be copied to the root of the project when the template is generated.
+
+Files in this global template folder will override any files in the default
+template, so you can for example change the `README.md` file, add to the
+`.gitignore` or even add a complete extra folder structure.
+
+If you want to do a major change to the template, you can actually dump the
+default template to this folder and modify or delete files as you see fit. See
+the next section for more information on how to do this.

docs/template/replace.md

@@ -0,0 +1,58 @@
+# Replacing the Default Template
+
+## Dump the Default Template
+
+Should you wish to heavily modify the default template, or even replace it
+completely, you can do so by dumping the default template to the
+`~/.pymaker/template` folder. This will copy all files from the default template
+to the global template folder, where you can modify or delete them as you see
+fit.
+
+To do this, run the following command:
+
+```console
+$ pymaker template dump
+```
+
+This will copy the default template to the global template folder
+(`~/.pymaker/template`). You can then modify or delete files as you see fit.
+
+Running this command will ask you if you wish to set this exported template as
+the default template. It will then ask you if you want to disable the internal
+template. If you answer yes, then the internal template will be
+disabled, and ONLY the exported template will be used instead. Otherwise, both
+will still be used with the exported template taking precedence.
+
+## Change the location of the Template folder
+
+If you wish to change the location of the template folder, you can do so in 2
+ways:
+
+1. By adding the `--local` flag to the above command (e.g. `pymaker template
+   dump --local`). This will dump the default template to the current folder,
+    giving you the option to disable the default template if needed. Note that
+    any files in the folder will be overwritten.
+2. By changing to the folder containing your template and running `pymaker
+   template set`. This will set the current folder as the template folder and
+   give you the same option to disable the default template.
+
+You can reset the template location back to the default `~/.pymaker/template`
+folder by running the following command:
+
+```console
+$ pymaker template reset
+```
+
+## Choose to use the Default Template or not
+
+Running the `dump` command will give you the option to disable the default
+template completely and ONLY use the exported template. You can also do this (or
+revert back to the default template) by running the following command:
+
+```console
+$ pymaker template default <enable|disable>
+```
+
+`enable` will enable the default template, and `disable` will disable it. Please
+note that any custom templates you have created will still be used, and will
+overwrite the default template if they have the same file name.

mkdocs.yml

@@ -55,5 +55,10 @@ nav:
   - Installation: installation.md
   - Quick Start: quick-start.md
   - Configuration: configuration.md
+  - Templates:
+      - Internal Template: template/internal.md
+      - Modifying: template/modify.md
+      - Replacing: template/replace.md
   - Task Runner: tasks.md
+  - Future Plans: future-plans.md
   - License: license.md