API documentation improvements

[duposyl]

1. Fixed ansys.stk.core.stkengine.stkengine by renaming stkengine.py to __init__.py.

2. Moved the Windows platform checks in stkdesktop.py to be at the method level instead of at the file level, so the API doc gets generated even when the doc build is running on Linux.

3. Revisited issue with * in docstrings. Only issue is with *. (star character followed by period). So, reverted some of the previous changes when that pattern was not used. Where it was used, mostly for file extensions, removed the star and just used the extension (for instance: .txt instead of *.txt).

[duposyl]

Here is some background on this issue, and more details on the usages of * in docstrings.

Initially, when the doc build broke complaining about * characters used in docstrings, we blindly changed all the *' characters to \\*. This fixed the problem and got the doc build to pass, but it had a side effect on the output of the help function. Here is an example. The docstring """A volumetric radius of the central body (a*b*c)^(1/3).""" was changed to """A volumetric radius of the central body (a\\*b\\*c)^(1/3).""". That fixed the doc build but then the output of the help function looked like this:

In order to avoid the help output side effect, the issue was revisited to better understand where * can be used or not.

It turns out that the only limitation is with *. (star followed by period). The other usages of * are fine. For instance, restoring the original * usage in the following docstrings:

worked fine and produced the expected doc output:

The only problematic case is *. which is mostly used to document file extensions:

generated the following error:

A few things were tried but did not fix the doc build breakage:

• Replacing the () by [] (i.e. [*.grv]).
• Removing (), i.e. just *.grv without the enclosing parens.
• Using single quote around the file extension, i.e. '*.grv'.

However, two patterns successfully addressed the issue:

• Using backticks around the file extension.
  
  which generated documentation with italics around the filename:
  
  In that approach, the backticks also showed up when using the help function, which is not very desirable:
  
• Removing the star and just using .ext.

After discussions, we decided that removing the * character to indicate file extensions was the best option. Here is how it looks after the change:

We also implement a check as part of the internal CI process to detect if this pattern is re-introduced in the API documentation, so we can detect the issue as early as possible when a developer submits our changes our API.

[jorgepiloto]

Thanks a lot for all your effort working with this, @duposyl. I checked doc-artifacts and everything renders as expected. Merging 🚀