[scribus] A new Scripter API documentation

[ZASKE Martin]

Hi a.l.e,

thank you for your efforts and for sharing your work.


I went right away and had a look at your sample output. Looks very nice.
And it would be re-assuring to have such scripted always-fresh
documentation.


Not as a criticism but as input to make it even more useful:

Have the script produce clear mentions of the date and the concerned
Scribus version for each page or at least on the start-page.




For having a closer look, I went straight to my old friend "image
export". Very very useful for our workflow (yes, I know, some people
always want to take the detour via PDF-export, but we got our reasons).
	So I was surprised to find it under "View" as "class ImageExport". But
that is exactly why your approach has got so much potential: Even us
non-Scribus-programmers are learning about the underlying structures
from your documentation which comes straight from the code/docstrings.
And that can only help with our humble scripts for our own projects.

I am still puzzled about certain details in ImageExport but at least I
no longer need to think "Wonder how many years this API-help is lagging
behind the actual Scribus API?".


So thanks again for all your "lateral tinkering" and for sharing, I keep
learning about Scribus from many of your ideas,

Martin




On 15.08.2020 13:09, 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.
> 
> Have fun
> a.l.e
> 
> ___
> Scribus Mailing List: scribus at lists.scribus.net
> Edit your options or unsubscribe:
> http://lists.scribus.net/mailman/listinfo/scribus
> See also:
> http://wiki.scribus.net
> http://forums.scribus.net
> 


-- 
ZASKE Martin
responsable GʊGʊ
BP 50 - Bassila - Bénin
tel GʊGʊ 66.66.11.11
tel pers 97.44.62.95