[scribus] A new Scripter API documentation

[ale rimoldi]

hi greg

thanks for your comments and suggestions


> The challenge with the Scripter documentation is that often the
> docstrings aren't enough to understand how to use the command.

this is not the documentation for the scripter, it's the
documentation of the scripter API.

this is something that is useful for every scripter programmer, not
only for beginners.

the scripter documentation / an introduction to scripting is very
useful and necessary but  should IMO be kept as a separate document.

> A
> number of those who attempt to use Scripter aren't highly experienced
> with Python, and would benefit from examples.

you're completely right, and i love the php documentation exactly for
that (i don't know it's current status, but it used to be that
way).

i can indeed easily extend my script to import files that
better describe the usage of the single commands.
sadly, because of the the legacy you point to, we cannot use the current
document documentation to do so.

finally, i'd really like to keep the API as small as possible and only
as big as necessary.

so:

- the docstrings from the code should correctly and succinctly
  describe the command
- we can have usage examples in an external source. 

> I wonder if you could add a feedback method to your documentation, so
> people can ask questions

yes, that should be possible (and it's something that the php
documentation used to do very well)

there are ways to link to github / gitlab issues or it's possible to
add an external comment engine.

have a wonderful sunday!
a.l.e