Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor tasks documentation #77

Open
4 tasks
sergei-maertens opened this issue Sep 10, 2020 · 0 comments
Open
4 tasks

Refactor tasks documentation #77

sergei-maertens opened this issue Sep 10, 2020 · 0 comments
Labels
documentation Improvements or additions to documentation

Comments

@sergei-maertens
Copy link
Contributor

Currently task documentation is mostly visible via the /taskmappings endpoint, which poses a number of problems:

  • long list of configured tasks, lack of overview/grouping
  • only displays tasks that are connected to a topic, not all available tasks

One of the goals is to have BPTL documentation available for non-technical people so they get an idea of which generic building blocks are available. A grouping of the tasks per topic/domain (the python packages are already structured this way!) in the presentation layer would provide a first improvement.

Other improvements are:

  • documentation (aspects) in Dutch
  • more textual and less technical documentation

A new documentation section should facilitate this. We can add this to the existing setup and gradually replace existing pages.

Acceptance criteria:

  • A new entrypoint/page for documentation
  • All available work units' documentation can be viewed, even if not connected to a topic
  • Work units are grouped per domain (ZGW, Camunda, ValidSign...)
  • Documentation is extracted from docstrings - limited to general descriptions.

Nice to have:

Improved documentation parsing/system to document work units. A decorator-like approach could be viable, something like:

@register
@task.variable("zaakUrl", "URL reference to the zaak", required=True, type=str)
def example_task(task: BaseTask):
    do_stuff()
    return {}

but this could also be handled by function ArgSpecs or other formats (Sphinx arg docs for example).

@sergei-maertens sergei-maertens added the documentation Improvements or additions to documentation label Sep 21, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

1 participant