1.3. Usage¶
Note
For the following steps groundwork must be installed.
If not done yet, please follow Installation.
In the last chapter Installation you may have already noticed that groundwork has its own little execution command. groundwork tries to help you as early as possible inside your personal development process.
This means it is not only focused on providing functions for your code. It can also help you with setting up new projects or analysing and understanding existing projects.
But lets start with the basics by calling it:
>>> groundwork
Usage: groundwork [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
doc Shows the documentation
doc_list List all documents
doc_write Stores documents as files
plugin_list List all plugins
receiver_list List of all signal receivers
recipe_build Builds a given recipe
recipe_list Lists all recipes
signal_list List of all signals
Calling groundwork without any parameters will show you the above help message. As you can see, you get a nice list of available commands.
If you need more information to a specific command, execute groundwork <command> --help
. Example:
>>> groundwork doc_write --help
Usage: groundwork doc_write [OPTIONS] PATH
Stores documents as files
Options:
-h, --html Will output html instead of rst
-o, --overwrite Will overwrite existing files
-q, --quiet Will suppress any user interaction
--help Show this message and exit.
1.3.1. Real-time documentation¶
Plugins are allowed to register documents, which can contain static text or dynamic information like currently active plugins.
Because the command groundwork starts itself a groundwork based application, we can easily examine this application by taking a look into the registered documents:
>>> groundwork doc
groundwork basic app
====================
Application overview
--------------------
Path: /.
Active plugins: 5
Registered commands: 8
Registered signals: 4
Registered receivers: 10
Registered documents: 7
---------------------------------------------------------------------------
This document is registered by 'groundwork basic app' under the name 'main'
---------------------------------------------------------------------------
Actions: [N]ext, E[x]it
Select your action [N]:
This starts a console based document viewer and you can use the keys N and P + ENTER to see next or previous chapter. To exit just type x and press ENTER
In one of the last lines you see which plugin has registered the currently showed document and you see the internal, unique document name.
You will find documents for registered commands, signals or plugins.
The page plugin_classes
shows you an overview about all registered plugins inside the currently used
Python Environment. This means each groundwork application could use this plugins by just adding their names to
its config. We will do this in the next chapter First own project.
To get an overview about all used plugins by the current application, open the page plugins_overviews
.
Documents are supporting RST and Jinja and therefore can be easily transformed to any kind of presentation. You can view them on console, export them to sphinx or read them on a webpage. And documents are always up to date, as their content is mostly calculated during runtime.
1.3.1.1. Exporting documents¶
The GwDocumentInfo
plugin has registerd a command, which exports and stores documents on a hard disk.
Let’s say we want the documents as RST output in the folder temp:
>>> mkdir temp
>>> groundwork doc_write temp
Storing groundwork application documents
Application: groundwork basic app
Number of documents: 7
Going to write to following files:
signals_overview.rst
main.rst
plugins_classes.rst
documents_overview.rst
plugins_overview.rst
receivers_overview.rst
commands_overview.rst
Target directory: /.../temp
Shall we go on? [Y]es, [N]o: : y
signals_overview.rst stored.
main.rst stored.
plugins_classes.rst stored.
documents_overview.rst stored.
plugins_overview.rst stored.
receivers_overview.rst stored.
commands_overview.rst stored.
As you can see, for each virtual document a rst file was created:
>>> tree temp # linux command
temp
├── commands_overview.rst
├── documents_overview.rst
├── main.rst
├── plugins_classes.rst
├── plugins_overview.rst
├── receivers_overview.rst
└── signals_overview.rst
That’s it. On the next chapter we will use the recipe_build
command to create our first own groundwork project.
Go on with First own project.