Skip to content

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

@jtherrmann

Description

@jtherrmann

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?

Metadata

Metadata

Assignees

No one assigned

    Labels

    Jira BugCreate a Jira Bug for this issue

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions