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

Fix rendering of documentation derived from source code at hyp3-docs #369

Open
jtherrmann opened this issue Oct 5, 2023 · 0 comments
Open
Labels
Jira Bug Create a Jira Bug for this issue

Comments

@jtherrmann
Copy link
Contributor

jtherrmann commented Oct 5, 2023

Jira: https://asfdaac.atlassian.net/browse/TOOL-2261

Note: The above link is accessible only to members of ASF.


  1. Since deploying the mkdocs-asf-theme upgrade (see Upgrade mkdocs-material mkdocs-asf-theme#38) to https://jhkennedy.org/hyp3-docs, I'm seeing an issue where the file paths in source code blocks fail to render if they're too long, e.g. see the source code blocks at the top of https://jhkennedy.org/hyp3-docs/using/sdk_api/. After deploying the upgrade to our production hyp3-docs website, we should confirm that the problem still exists at https://hyp3-docs.asf.alaska.edu/using/sdk_api/. The solution would be to convert the file paths to relative paths, e.g. /usr/share/miniconda/envs/hyp3-docs/lib/python3.9/site-packages/hyp3_sdk/jobs.py should be hyp3_sdk/jobs.py (which we should do regardless of the file path rendering issue).
  2. I believe also on https://jhkennedy.org/hyp3-docs/using/sdk_api/, Forrest (using Safari on Mac) reported seeing long function signatures run off the visible area of the page (rather than wrapping to a newline, as they do for me, on Linux). After deploying the theme upgrade, we should confirm the problem still exists at https://hyp3-docs.asf.alaska.edu/using/sdk_api/, and decide if it's worth fixing (maybe not, if it only affects Safari).
  3. When a docstring includes a Python interpreter example prefixed with >>>, the corresponding documentation renders strangely, e.g. https://hyp3-docs.asf.alaska.edu/tools/asf_tools_api/#asf_tools.tile. Maybe using backticks in the docstring would help?
@jtherrmann jtherrmann added the Jira Bug Create a Jira Bug for this issue label Oct 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Jira Bug Create a Jira Bug for this issue
Projects
None yet
Development

No branches or pull requests

1 participant