search

SasView / sasdata

Package for loading and handling SAS data
BSD 3-Clause "New" or "Revised" License
1 stars 2 forks source link

55: Generate Developer Docs #56

Closed krzywon closed 10 months ago

krzywon commented 11 months ago

As noted by @smk78, the developer documentation was not present in the build. This PR corrects that mistake.

To check the docs are bundling with sasview properly, please check the builds in https://github.com/SasView/sasview/actions/runs/7121411183/

Fixes #55

smk78 commented 11 months ago

Tested https://github.com/SasView/sasview/actions/runs/7121411183/ on W10/x64.

This PR has indeed fixed the broken sasdata API doc build.

However, it has not addressed a couple of things from my review on #53 .

1) When you go to Developer Documentation you see this: image which would be fine, if the link to sasdata overview did give an overview in the same way sasmodels overview does. But all it does is link to this: image which, in turn, links to API docs: image etc. So my question here is what exactly is the role of /doc/dev/sasdata-dev/dev.html? It seems to be redundant? In which case, why not do away with it and change the top level link from sasdata overview to sasdata API?

2) The documents /doc/user/data/data/data_import_help.html and /doc/user/data/data/data_export_help.html are still not linked from anywhere (not even from the 'API' docs) and are only accessible through the search box.

krzywon commented 11 months ago

@smk78 - I agree with your first point and just pushed a change to remove the unneeded documentation level.

As far as your 2nd point, the data_import and data_export help files are specific to the sasdata scripting interface. All of the same information is available in the sasdata developer docs. I purposely omitted those two files from the SasView docs, because the information isn't relevant to the users of the GUI-based program.

butlerpd commented 11 months ago

As far as your 2nd point, the data_import and data_export help files are specific to the sasdata scripting interface. All of the same information is available in the sasdata developer docs. I purposely omitted those two files from the SasView docs, because the information isn't relevant to the users of the GUI-based program.

So reading @smk78 comment -- does this mean these files are orphans because they are duplicates? in which case should we delete them? or are you saying those files are linked through the sasdata developer docs? I worry about "same information" available elsewhere as it makes maintenance a nightmare 😄.

krzywon commented 11 months ago

So reading @smk78 comment -- does this mean these files are orphans because they are duplicates? in which case should we delete them? or are you saying those files are linked through the sasdata developer docs? I worry about "same information" available elsewhere as it makes maintenance a nightmare 😄.

The two are not orphans, they are bundled with the sasdata package. They are user documentation with more explicit instructions on data import and export using a scripting interface. SasView users don't need that level of detail because they will use the Data Explorer for that, and that already has separate documentation.