Overall doc review for public release #143
Conversation
github-actions
bot
added
the
documentation
| By default, this file is located in the user config directory (platform-dependent). | ||
| Its location can be specified explicitly with the ``ANSYS_LAUNCHER_CONFIG_PATH`` | ||
| environment variable. | ||
| The methods in the ``config`` class manage the default configuration |
There was a problem hiding this comment.
All of the code entities in this paragraph have a noun after them, which is the what the Google developer documentation style guide recommends. However, there are many occurrences of code entities where the noun does not follow. If I felt fairly confident what the noun should be, I added it. Oftentimes, I did not feel confident so did not. This is minor and something that can be done later. I just wanted to point out how we might want to make edits later to more closely follow the styleguide.
| @@ -1,9 +1,9 @@ | |||
| .. _cli: | |||
|
|
|||
| Command line reference | |||
| Command-line interface | |||
There was a problem hiding this comment.
I'm still unsure if the user guide is the right place to put this section. I'd appreciate your input @PipKat:
The content of this section is an auto-generated reference of the command-line options, similar to an API reference (but for the CLI).
Should this:
- remain here (user guide)
- get its own top-level section
- be moved into the "API reference" section
?
There was a problem hiding this comment.
The more explanatory documentation for the CLI is included in the "Getting started", and "Examples" sections.
There was a problem hiding this comment.
@greschd I think that having it in the "User guide" section is fine. I did wonder if maybe the "Rationale" section should be first though--since it did a good job explaining why I would want to use this utility.
There was a problem hiding this comment.
Yeah, I think that makes sense. In general, these docs have two audiences:
- developers of other PyAnsys packages
- users of the CLI, which are end-users of the PyAnsys packages
But I think it makes sense to put the rationale page (aimed at other PyAnsys devs) first, simply because the end-users will likely find this through the docs of the library they're directly using first, which can directly link to the right section.
|
Thanks a lot for the review @PipKat. It looks good overall from my side; I've just added some minor tweaks. |
Apply feedback from dev review Co-authored-by: Dominik Gresch <greschd@users.noreply.github.com> Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com>
|
@RobPasMue @greschd Thanks so much for your thorough review. You caught quite a few errors on my part, which is much appreciated! @greschd I'll let you resolve the last few comments and merge this PR when you are fully satisfied with it! |
|
Thanks again for your review @PipKat! Awesome work 🎉 |
Because "entrypoint" was used almost three times as frequently as "entry point," I changed all occurrences to"entrypoint" descriptive text . Otherwise, I reorganized the README and doc landing page to follow the conventions we've adopted recently. Our overall goal is to provide information (such as installation) in one place only and then reference that place from elsewhere.
The links in the README to the doc sections now point to the
devdoc folder so that they work. However, prior to release, they will have to be changed to thestabledoc folder.@RobPasMue I've marked the doc review as completed in Issue #130. You can merge this PR as is or first address my very few comments and then merge.