Merge pull request #23 from seapagan/add-docs

Add a documentation site

README.md

@@ -1,5 +1,7 @@
 # Py-Maker <!-- omit in toc -->
 
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/7c86940f816b455ab171dc8126476849)](https://app.codacy.com/gh/seapagan/py-maker/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+
 This is a command line tool to help you create new Python projects.  It will
 create a new directory for your project, initialise a git repository, create a
 virtual environment, and install some basic dependencies.

TODO.md

@@ -7,3 +7,4 @@
   a new command to create and edit the settings
 - 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)
+- check manually entered package name to ensure no dashes.

docs/css/extra.css

@@ -0,0 +1,12 @@
+.task-list-item2 {
+  list-style-type: none;
+}
+
+.task-list-item input {
+  margin: 0 4px 0.25em -4px;
+  vertical-align: middle;
+}
+
+.md-nav--primary .md-nav__title {
+  display: none;
+}

docs/index.md

@@ -0,0 +1,40 @@
+# Py-Maker
+
+This is a command line tool to help you create new Python projects.  It will
+create a new directory for your project, initialise a git repository, create a
+virtual environment, and install some basic dependencies.
+
+Latest Version : {{ latest-git-tag }}
+
+## Testing
+
+The generated project includes
+[pytest](https://docs.pytest.org/en/latest/){:target="_blank"} and some related
+plugins to allow you to set up testing straight away.
+
+Write your tests in the `tests` directory and run them with `pytest`.
+
+## Linting
+
+The generated project includes
+[flake8](https://flake8.pycqa.org/en/latest/){:target="_blank"} (with several
+plugins) for linting and
+[Black](https://black.readthedocs.io/en/stable/){:target="_blank"} for
+formatting. [Mypy](http://mypy-lang.org/){:target="_blank"} is installed for
+type checking. [isort](https://pycqa.github.io/isort/){:target="_blank"},
+[Pylint](https://pylint.org/) and
+[tyrceratops](https://github.com/guilatrova/tryceratops){:target="_blank"} are
+also installed as standard.
+
+## Pre-commit
+
+The generated project uses [pre-commit](https://pre-commit.com/) to run some
+checks on the code before it is committed.  This is a great tool to help keep
+your code clean.
+
+To install pre-commit, run the following command from inside your venv:
+
+```console
+$ pre-commit install
+pre-commit installed at .git/hooks/pre-commit
+```

docs/installation.md

@@ -0,0 +1,27 @@
+
+# Installation
+
+It is probably better to install this package globally, rather than in a virtual
+environment, as it is intended to be used to create new projects. Since we are
+using [Poetry](https://python-poetry.org/){:target="_blank"} to manage the
+dependencies, a virtual environment will be created for you anyway specific to
+each project you are creating.
+
+Install the package globally using pip:
+
+```console
+$ pip install py-maker
+```
+
+If you cannot install globally due to permissions, you can install it to your
+user install directory:
+
+```console
+$ pip install --user py-maker
+```
+
+or use [pipx](https://pypa.github.io/pipx/){:target="_blank"}
+
+```console
+$ pipx install py-maker
+```

docs/license.md

@@ -0,0 +1 @@
+--8<-- "LICENSE.txt"

docs/quick-start.md

@@ -0,0 +1,94 @@
+# Quick Start
+
+To create a new project, run the following command:
+
+```console
+$ pymaker new <project-folder>
+```
+
+This will create a new directory with the name you provide.
+
+You can create a new project in the current directory by using `.` as the
+project folder name. This must be an empty directory:
+
+```console
+$ mkdir test-project
+$ cd test-project
+$ pymaker new .
+```
+
+The App will then run the steps needed to get you started quickly:
+
+1. Copy the template files into the new directory
+2. Initialise a git repository
+3. Commit the boilerplate to Git
+
+You will be asked a series of questions to customise the new project.
+
+When it asks "Package Name?" you can choose two variants :
+
+1. **If you are creating a standard Python package** that can optionally be
+   uploaded to **PyPI**, enter a package name here. Note that underscores ("_")
+   must be used as opposed to dashes ("-") to comply with Python package naming
+   rules. Default is the project folder name with underscores replacing dashes.
+2. **For a stand-alone tool** that will not ne uploaded to PyPI, or is not a
+   library, enter '-' for the package name. In this case the `main.py` will just
+   be placed in the project root and no package folder will be created or
+   referenced.
+
+You should now change into the new directory, install dependencies and activate
+the virtual environment:
+
+```console
+$ cd <project-folder>
+$ poetry install
+$ poetry shell
+```
+
+Now, you can start developing :smile:
+
+Example run :
+
+```console
+$ pymaker new test-project
+PyMaker - Generate a Python project skeleton.
+
+Creating a new project at /home/bathroom/test-project
+
+Name of the Application? (Test Project):
+Package Name? (Use '-' for standalone script) (test_project):
+Description of the Application?: An amazing Bigly test project. better than you've ever seen before!
+Author Name? (Orange Tango):
+Author Email? ([email protected]):
+Application License? [None/Apache2/BSD3/BSD2/GPL2/GPL3/LGPL/MIT/MPL2/CDDL/EPL2] (MIT):
+
+Creating a New Python app with the below settings :
+
+    Description : An amazing Bigly test project. better than you've ever seen before!
+   Package Name : test_project
+         Author : Orange Tango
+          Email : [email protected]
+        License : MIT
+    Project Dir : /home/bathroom/test-project
+           Name : Test Project
+
+Is this correct? [y/n] (y): y
+
+--> Creating project folder ... Done
+--> Creating Git repository ... Done
+
+--> Project created successfully.
+
+Next steps:
+
+    1) Change to the project directory:
+    2) Install the dependencies (creates a virtual environment):
+        'poetry install'
+    3) Activate the virtual environment:
+        'poetry shell'
+    4) Run the application:
+        'test-project'
+    5) Code!
+
+See the README.md file for more information.
+```

docs/tasks.md

@@ -0,0 +1,27 @@
+# Task Runner
+
+The task-runner [Poe the
+Poet](https://github.com/nat-n/poethepoet){:target="_blank"} is installed as a
+development dependency which allows us to run simple tasks (similar to npm
+`scripts`).
+
+These are run (from within the virtual environment) using the `poe` command and
+then the script name, for example:
+
+```console
+$ poe pre
+```
+
+You can define your own, but there are 7 specific ones provided with the script.
+
+- `pre` : Run `pre-commit run --all-files`
+- `pylint`: Run Pylint on all Python files in the project.
+- `mypy` = Run MyPy type-checker on all Python files in the project.
+- `flake8` = Run Flake8 linter on all Python files in the project.
+- `black` = Run Black code formatter on all Python files in the project.
+- `try` = Run Tryceratops linter on all Python files in the project.
+
+- `lint` = Runs pylint, mypy, flake8 and black in sequence
+
+These are defined in the `pyproject.toml` file in the `[tool.poe.tasks]`
+section. Take a look at this file if you want to add or remove tasks.

mkdocs.yml

@@ -0,0 +1,58 @@
+site_name: PyMaker
+site_url: https://pymaker.seapagan.net/
+
+theme:
+  name: material
+  palette:
+    primary: light-blue
+    accent: blue
+  features:
+    - navigation.footer
+    - navigation.expand
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/seapagan/py-maker
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/gnramsay-dev
+
+copyright: © 2023 Grant Ramsay (Seapagan)
+
+plugins:
+  - search
+  - git-revision-date-localized:
+      enable_creation_date: true
+  - mkdocstrings
+  - latest-git-tag
+  - minify:
+      minify_html: true
+      minify_css: true
+      minify_js: true
+      htmlmin_opts:
+        remove_comments: true
+        remove_empty_space: true
+
+repo_url: https://github.com/seapagan/py-maker
+repo_name: seapagan/py-maker
+
+markdown_extensions:
+  - admonition
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      linenums: false
+      auto_title: false
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+
+extra_css:
+  - css/extra.css
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Quick Start: quick-start.md
+  - Task Runner: tasks.md
+  - License: license.md