View Issue Details

IDProjectCategoryView StatusLast Update
0016213ScribusScripterpublic2020-09-04 07:09
Reporterale Assigned To 
PrioritynormalSeverityfeatureReproducibilityN/A
Status newResolutionopen 
Product Version1.5.6.svn 
Summary0016213: creating the scripter API doc from the doc strings
Descriptioncurrently, the scripter API doc does not always reflect the state of the API itself.

on top of the license issue, the doc being stored at a different place than the code makes it hard to keep it in sync with the changes in the code.

also, when searching for help in the API most results are from the GUI doc.

for these reasons i suggest to:

- automatically generate the API doc from the doc strings
- keep the API help separated from the "normal" help
- provide the API doc online (this has been requested a few times)

inspired by the complaints by one of the top developers of a libre grahpics program, i've been working on improving https://wiki.scribus.net/canvas/Category:Scripts#Auto-Output_all_Scripter_Commands (and a script that has been created based on it) to produce the API doc and this is what it currently produces:

http://impagina.org/scribus-scripter-api/

there are still a few small issues in the script but it looks already rather good to me.

in order to improve the output i suggest:

- to make sure that the docstrings can easily be exported as markdown (and then converted into html)
- improve the signature in the first line of the docstring to look like the typed (optional) signatures:
  - `setInfo(author: str, info: str, description:str) -> bool
  - `getAllObjects(page: int = None) -> list
- improve the naming of the commands so that it's "easier" to match them to the doc sections (and it also make it easier for the script programmer to recall what a command is named...)

what are your thoughts?
TagsNo tags attached.
PatchNo

Activities

ale

2020-08-15 08:48

manager   ~0047938

voilĂ , the current state of

http://impagina.org/scribus-scripter-api/

is now more than ok.

i don't think that there is much i can do to improve it, without first modifying the docstrings in the c++ code.

the script that creates the markdown files is published here:

https://github.com/aoloe/scribus-script-repository/tree/master/export-scripter-api

should i go on and create a help new engine that uses this information to provide up to date and focused help for the scripters?

cbradney

2020-08-16 16:20

administrator   ~0047945

I think the text (ie docstrings in the python related code) should go away. It should be stored out of the code if possible.

Yes, we need a new help system to replace the current one. I suppose markdown based instead of html

jghali

2020-08-16 17:39

administrator   ~0047949

>> I think the text (ie docstrings in the python related code) should go away.

The docstrings are in fact used by Python to provide help in the console. Type for example help(messageBox) in the console and you'll get the corresponding help for messageBox function. Not sure if we want to remove that functionality.

Compared to docstrings, current html help is however sometime enriched by html links to other part of documentation. Not sure how to put the html links information in docstrings so that they get translated into proper links in generated documentation.

ale

2020-08-17 07:58

manager   ~0047953

jean, on the one side i'd like to keep the api documentation as simple as possible.

but if links are needed we could easily do that through markdown (or other simple markup) that gets interpreted during the conversion to markdown / html...

and concerning the docstring... i guess that since there is not real scribus python module, their interest is limited but, on the other side, it's a good practice to provide them.
i really have mixed feeling about them.
all in all, i think i'd prefer to have them in the scripter.

my issue is with the fact that scribus has two parallel documentations for the API and one is not as good as it could be (the docstrings) and the other is often outdated, out of sync and also not as good as it could be.

having only one source that can somehow be automatically checked with the code would imo improve the situation.
i've put "lot" of work in one possible solution (because if it's not implemented it's hard to start a discussion...) but i'm open to any good solution that produces a good API documentation while limiting the workload.

cbradney

2020-08-17 10:16

administrator   ~0047955

What you have produced on that site looks ok to me. and the system to produce looks ok too. Maybe we could use that for all docs?

ale

2020-09-03 19:43

manager   ~0048029

Last edited: 2020-09-04 07:09

yes, having the documentation in markdown is imo a good idea.

there are multiple tools for converting the markdown files into html.
mkdocs looks fine.
but it should not be hard to use a different one later.

Issue History

Date Modified Username Field Change
2020-08-14 06:39 ale New Issue
2020-08-15 08:48 ale Note Added: 0047938
2020-08-16 16:20 cbradney Note Added: 0047945
2020-08-16 17:39 jghali Note Added: 0047949
2020-08-17 07:58 ale Note Added: 0047953
2020-08-17 10:16 cbradney Note Added: 0047955
2020-09-03 19:43 ale Note Added: 0048029
2020-09-04 07:09 ale Note Edited: 0048029