[scribus] A new Scripter API documentation

[Gregory Pittman]

On 8/15/20 6:09 AM, ale rimoldi wrote:
> Hi Scribusers
> 
> Over and over, I've heard complains about the Scripter documentation
> (among other things, of course!).
> 
> Since the Scribus documentation is not really free, there was not much
> I was willing / able to do.
> 
> Last week, I got one more critical voice on the API documentation, and
> I've decided that it was time to see if it was possible to get to
> something sane, by exporting the API from the docstrings.
> 
> The starting point was the "good old"
> 
> https://github.com/aoloe/scribus-script-collection/blob/master/export-api-doc/export-api-doc.py
> 
> the final result is
> 
> https://github.com/aoloe/scribus-script-repository/tree/master/export-scripter-api
> 
> that can be used to produce
> 
> http://impagina.org/scribus-scripter-api/
> 
> (yes, people also asked for the API help to be published in the web)
> 
> Yeah, no more undocumented commands!
> Only one place where the command will be documented!
> 
> The final goal is to replace the hand crafted API help in the Scribus
> help by a separated Help entry (that will provide more focused search
> results).
> 
> If you have ideas on how to improve the script or the output, you're
> welcome to comment in here or in the bug tracker
> 
> https://bugs.scribus.net/view.php?id=16213
> 
> or in the scribus-script-repository Github repository linked above.
> 
> For those who are willing to help out, I could need a hand for
> improving the docstrings:
> 
> - modify all signatures in the docstrings to match the real Python
>   signatures ("getAllObjects(page: int=None) -> list" instead of
>   "getAllObjects(["page"]) -> list"
> - fix the formatting that do not convert well to Markdown/HTML (like
>   code snippets and lists)
> - a unified way of marking depracated functions
> - propose (and implement) name changes for functions that do not match
>   the overall naming schema.
> - generally, improving the docstrings to be more useful.

The challenge with the Scripter documentation is that often the docstrings aren't enough to understand how to use the command. A number of those who attempt to use Scripter aren't highly experienced with Python, and would benefit from examples.

Somewhere at the beginning, it would be good to talk about the difference between starting a script with 
import scribus
vs
from scribus import *
In particular, the first method requires you to add a prefix of "scribus." to every command, and also to Scribus-specific units, like "scribus.UNIT_MILLIMETERS". BTW, I like that you have collected together the various types of Scribus units and put them where they are used.

Perhaps with your new documentation, it might be possible to point out commands that don't work as expected. For example, I've never seen docChanged() do what it's supposed to do. If you set this, when the script ends, you should get a warning when you try to close Scribus if you haven't saved the document, but that doesn't seem to happen. With that in mind, I wonder if you could add a feedback method to your documentation, so people can ask questions (which can end up improving the docs) or point out commands that don't work (which can end up improving the commands).

Greg

P.S. The non-free nature of the docs is a legacy of the days of mrdocs, when I think it was anticipated that some day the documentation might be published outside of Scribus in some form. I'm not aware of anyone being pursued for doing whatever they want to do with the docs.