How to contribute to the documentation?

[felipemarkson]

This package assists me in several analyzes, but I believe that the documentation can be improved. How can I contribute to the documentation?

[PMeira]

Hi, would you like to contribute to any specific area of documentation?

Specifically to ODD.py, dss-extensions/dss_capi#77 and later dss-extensions/dss-extensions#22 will change quite a bit but should mostly simplify the code and hopefully docs.

As you probably noticed, none of the projects here in https://github.com/dss-extensions have much documentation. From my point of view, I didn't expect as many users before reaching 1.0 on most of the projects so I didn't plan on writing docs from the beginning.

To reduce duplication, I plan on providing some general API docs for all of them at once, including comparing the official COM API vs the COM-like and ODD-like projects from DSS Extensions. We have a growing number of API extensions and customizable behavior absent in the official OpenDSS. For some more complex future features (still private at the moment), I'm planning ahead and writing some basic docs as I evolve the ideas.

Depending on how things go, a dedicated repo could be created to both host these general docs and point better to the official OpenDSS docs, as well as hosting general issue tickets that could apply to all projects but are not specific to DSS C-API (our actual OpenDSS engine).

[felipemarkson]

I have more experience using de OpenDSSDirect.py and OpenDSSDirect.jl, specifically with the return of voltage and power loss methods.

I have mapped the data structures that some of these methods return and I could include them in the documentation.

This mapping is being performed during this project (for now documented in the pt-br language) that tries to facilitate the extraction of information from common distribution systems.

[PMeira]

@felipemarkson I finally outlined a plan on the general documentation idea here: dss-extensions/dss-extensions#6

Ideally we should be able to document most of the API side of things once. Since even OpenDSS as a whole is a niche project compared to a larger open-source project, it's unlikely we'll have the resources to maintain the docs updated for each project under DSS Extensions. Recently there's been some growth in DSS_MATLAB, for example -- there's no way I'll spend much time manually detailing the docs for that by itself, after each update of the API and the DSS engine.

I plan to finish the work on #78 and some extensive changes in the internal code of the DSS C-API library itself before taking some time to focus on the docs. In a few months, I hope that it'll be easier to contribute in general later. Even if you wouldn't be able to contribute later, please chime in if you have any suggestion on the process.

[felipemarkson]

Maybe, begin with dss_python using pytest's Doctest which can document and test in the same time. What do you think?

[PMeira]

I started populating https://github.com/dss-extensions/dss-extensions (we could transfer this ticket there)

I'm planning on dedicating a few days next week to leave it in a place where a lot more people can contribute. I should finish updating all projects to 0.12.x today (and releasing DSS C-API 0.12.1 due to the Voltexceptionreport issue).

Maybe, begin with dss_python using pytest's Doctest which can document and test in the same time. What do you think?

@felipemarkson That would help new users, but there would be a lot of duplication with https://sourceforge.net/p/electricdss/code/HEAD/tree/trunk/Version8/Distrib/x64/OpenDSS_COM.chm

We need more automated tests that exercise some less frequent used parts of the engine and extend cross-validation with the official version. Pascal doesn't have good coverage tools, but hopefully we will be able to integrate some tools when the code is in C++ and actually see what our tests are missing.

Long term we would probably merge the useful parts of the "classic" APIs into something like IObj.py (that's 44k lines but most are generated from our new DSS_ExtractSchema()).

But... I'm also considering adding a native COM implementation (or at least one based on dss_sharp) to make it even easier for users to migrate, especially considering this document from ANEEL (see page 25). Maybe using some variation of IDL (COM and WinRT use a form of IDL, the file for OpenDSS is in the repo) would be a good idea, but most of these kind of specification is for "dumb" data. Might be worth to experiment -- if it works, could be a good place to add general notes.

[felipemarkson]

I started populating https://github.com/dss-extensions/dss-extensions (we could transfer this ticket there)

Yes, I think it is more appropriate.

@felipemarkson That would help new users, but there would be a lot of duplication with https://sourceforge.net/p/electricdss/code/HEAD/tree/trunk/Version8/Distrib/x64/OpenDSS_COM.chm

I agree, but In my experience here on USP, the new users have many problems using this documentation, mainly because they don't have experience with COM interface, and this document does not have examples (I cannot open this on my notebook because I use Linux :/)

We need more automated tests that exercise some less frequent used parts of the engine and extend cross-validation with the official version...

Sure, I can also help with that. I have some experience using the GoogleTest for C/C++, but this is not a lightweight tool.

But... I'm also considering adding a native COM implementation...

What could be a native COM implementation? Do you mean the UI of OpenDSS?

[PMeira]

I agree, but In my experience here on USP, the new users have many problems using this documentation, mainly because they don't have experience with COM interface, and this document does not have examples

I see, I'll try to raise the point next week internally (IEEE PES GM is happening this week).

(I cannot open this on my notebook because I use Linux :/)

I'm mostly on Linux too, kchmviewer works fine, if not better than the native Windows viewer. Wine's viewer also works.

What could be a native COM implementation? Do you mean the UI of OpenDSS?

Well, a COM DLL. There are people that still use COM in MS Office and lots of legacy Windows software support COM too.

We can do that either wrapping the plain C-API DLL, or exposing the .NET assembly from DSS Sharp (which I just updated).

Do you mean the UI of OpenDSS?

GUI is a separate thing. We have a couple of efforts that should be made public by the end of 2022. The basic OpenDSS.exe GUI is very simple, it's mostly a bunch of buttons and menus that call "Text.Command = ...". The extra closed-source tools (OpenDSS Viewer, OpenDSS GIS, OpenDSS-G) seem to be all based on LabView. Most of what OpenDSS Viewer does is already done in https://github.com/dss-extensions/dss_python/blob/master/dss/plot.py.

[PMeira]

Complementing: OpenDSS-G, besides the basic GUI, seems to have a few extra features, but nothing that we couldn't add with Python too. OpenDSS GIS is not even public, but from the video it's a simple addon: https://www.youtube.com/watch?v=8ja0fDB3Rlg

[PMeira]

I think we're good to close this now.

The new site and some general docs are being added to: https://dss-extensions.org/docs

Since the updates, we will try to use Markdown for everything, using MyST where possible. Expect for the C headers, the docstrings for shared functions/properties at Python level can be updated in DSS-Python and propagated from there, or vice-versa (for ODD.py). Features specific for a package should of course be documented on the package itself.

To contribute something larger, either a new Markdown document or Jupyter notebook is the easiest way. For general stuff, the source for the main site docs is at: https://github.com/dss-extensions/dss-extensions/tree/main/docs

The ODD.py site was updated. It's still at https://dss-extensions.org/OpenDSSDirect.py/ and will remain there, but since the main site is now using Sphinx, the idea is to integrate all Sphinx sites, or at least cross-link them. Since there will be changes, the sites are being deployed "manually" (not on CI), but it should be automated when a stable framework is achieved.

I noticed a lot of people don't quite understand, at first, that ODD.py and the other bindings (even other languages) are not the engine. And the low commit activity leads some to believe that the projects are dead (instead of mature). I think integrating the sites will help -- we can do that for several of the projects under DSS-Extensions.

There are some related issues in https://github.com/dss-extensions/dss-extensions/issues

We need some supporting infrastructure to better handle the C header docs (or some IDL like I mentioned before) and the upcoming i18n/translations.

I'll open another issue to remember to add a contributing document later. It should be dss-extensions/dss-extensions#37