View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0016213 | Scribus | Scripter | public | 2020-08-14 06:39 | 2020-09-04 07:09 |
| Reporter | ale | Assigned To | |||
| Priority | normal | Severity | feature | Reproducibility | N/A |
| Status | new | Resolution | open | ||
| Product Version | 1.5.6.svn | ||||
| Summary | 0016213: creating the scripter API doc from the doc strings | ||||
| Description | currently, 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? | ||||
| Tags | No tags attached. | ||||
| Patch | No | ||||
|
|
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? |
|
|
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 |
|
|
>> 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. |
|
|
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. |
|
|
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? |
|
|
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. |
| 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 |
