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.