PyPlate
"It mostly works" ™©®
A program for creating and building CLI/GUI/Packages in Python from a template
Version 0.0.3
Table of Contents
Requirements
Downloading
There are two ways to get the code:
-
Download the latest release (the 'Source code (zip)' file should work an all platforms).
-
Or you can clone the git repo to get the latest (and often broken) code from the main branch:
$ git clone https://github.com/cyclopticnerve/PyPlate
Installing
If you downloaded the zip file, extract it and go to the 'install' directory:
$ cd ~/Downloads/PyPlate-<version>/install
where \<version> is the version number of the file you downloaded.
If you cloned the repo, just go to the 'install' directory:
$ cd ~/Downloads/PyPlate/install
Either way, run the install script:
$ ./install.py
Usage
PyPlate consists of two main programs, 'pymaker' and 'pybaker'. The first is used to create the project, and the second is used to build an existing project as its development continues.
Let us start with 'pymaker'.
PyMaker - Create the project
Before you do anything, you should take a look at the 'conf.py' file in '~/.local/share/pyplate/conf'. This file contains A LOT of information that is used when creating/building a project. Most of these are string values and file/folder names used in the program, which you are free to change. PyPlate does not yet support i18n/l10n for itself (meaning any strings in this file will not be i18n'ed), but that may be included at a later date.
This file also contains some functions that are run at various times during creating/building the project, such as before/after creating a project, before/after building a project, etc. These functions have been extended to the config file so you don't have to do a lot of mucking around in the source code, but be sure to take a look at those too.
Now run the script from the command line, in the directory where you want to create the project:
$ cd ~/Documents/Projects/Python
$ pymaker
Enter the required information, and 'pymaker' will create the required files and folders in a subdirectory of the current directory.
That's it! From there you are free to modify the projects in your favorite IDE.
PyBaker - Build the project
Once you have created a project, you can use 'pybaker' in the project's directory to update metadata in the project's files and create a 'dist' folder. If you are using VSCode, you can select 'Terminal/Run Build Task...' from the menu bar or press 'Ctrl+Shift+B'.
'pybaker' is a program which will replace certain values in the project directory. These values are read/written in the 'project.json' file in your project's 'pyplate/project.json' file. Things like version number, short description, and other values that might change during a project's lifecycle are placed here.
The values in the 'pyplate/project.json' file can be edited at any time, followed by re-running 'pybaker'.
Note that if you are running pybaker from VSCode, it will ask for the name of the project (since it may not know the current directory). Give it the name of the project's directory as it was created by pymaker, relative to the current dir in VSCode's terminal.
Documenting you project
You can document your project using either pdoc3 or MkDocs.
Step 1: - Create your project using pymaker - Publish your repo to GitHub
Step 2: - To use pdoc3, you have to: - Open you GitHub repo in a browser - Go to the repo's Settings/Pages - Set the source to your main branch / docs folder
- To use MkDocs, you have to:
- run 'pybaker' from your project directory
Wait a minute or two, and your docs should appear at https://\<username>.github.io/\<repo_name>
Uninstalling
Go to the source folder for PyPlate and run the uninstaller:
$ cd ~/.local/share/pyplate/uninstall
$ ./uninstall.py
Documentation
See the documentation
Notes
If you make any changes to this template to better suit your own style/setup, please let me know or send a pull request. I will take a look and see if I can incorporate your changes to make them user, system, and/or IDE agnostic. This way the template can hopefully become more customizable to suit everyone's needs.
PyPlate currently uses pdoc3 for documentation, mostly because it is easy and sphinx is HARD! I don't really want to learn RST, and the Markdown/MyST stuff is confusing. I am currently looking at mkdocs, will let you know.
-)