Skip to content

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

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?

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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