Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Follow ups to first doc edit for public release #281

Closed
6 tasks done
FedericoNegri opened this issue Jan 23, 2024 · 0 comments · Fixed by #316, #321 or #336
Closed
6 tasks done

Follow ups to first doc edit for public release #281

FedericoNegri opened this issue Jan 23, 2024 · 0 comments · Fixed by #316, #321 or #336
Labels
documentation Improvements or additions to documentation

Comments

@FedericoNegri
Copy link
Contributor

FedericoNegri commented Jan 23, 2024

Originally posted by Kathy: #278 (comment)

  • The README file for a PyAnsys library usually has a "License" section. See the PyAEDT README file. Does such a section need to be added to the PyHPS README file? Note that the links in the README file for the documentation and its sections will have to be updated with the URLs for the stable documentation once the library is released. The current links are to the documentation for the dev version because it is currently the only version that exists.
  • The installation information in the "Getting started" and "Contribute" sections will have to be updated to convey the steps appropriate for the library once it is made public.
  • In the "User guide" section, I'd recommend breaking out the content currently on the landing page into these additional pages: Query parameters, Objects versus dictionaries, Common tasks, and Exception handling. (There is likely a better name than "Common tasks" for this how-to usage content. However, I couldn't easily come up with one!) I didn't want to make such changes in this PR because it will already have conflicts with changes Kerry has made in the PR for her technical review. If you want me to do a reorganization of this section in another PR after both this and Kerry's PRs are merged, let me know.
  • The "Examples" section is now showing links in the left navigation pane, although in the previous doc build it wasn't!? Also, should the landing page for this section (and examples) show the default username and password--and what format is the version provided in? (Usually it's in three digits [such as 241] rather than written as "2024 R1"). Lastly, I fixed minor grammar errors in the files shown via includes. For example, I changed "setup" to "set up" when it was used as a verb. However, I hope it was OK to edit the files that appear via includes because they are also included in the ZIP file for the example (and I don't know how/when this ZIP file is generated). ADDITION: For includes, consider using the start_at attribute to omit licensing information showing in the doc? This would save a lot of screen space.
  • In the "API reference" section, the right navigation pane only shows links to the top-level sections. It is really hard to find information within these sections. In the auth.rst file, there is a TODO REVIEW paragraph that must definitely be removed! Also, lots of objects are missing descriptions. Would we be able to improve this section before releasing publicly?
  • Rename REP to HPS
@FedericoNegri FedericoNegri added the documentation Improvements or additions to documentation label Jan 23, 2024
@sa-cross sa-cross pinned this issue Feb 16, 2024
@sa-cross sa-cross unpinned this issue Feb 16, 2024
This was linked to pull requests Feb 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
1 participant