Skip to content

Documentation cleanup needed

Many thanks to D.R. Evans for pointing out several documentation discrepancies in a separate email. His report motivated this "umbrella" issue to clean up geomag-algorithms' documentation, a project that was initiated over 3 years ago, but left half-finished near the end of 2021:

  • README.md

    • Github issue tracker is no longer used (we should point to Gitlab issues)
    • geomag-data email list (remove; look into Gitlab "Service Desk" option)
    • email jmfee (change to erigler; look in to Gitlab "Service Desk" option)
    • Waffle board (can point to Gitlab "issue board", but this should only be in develop.md)
    • folder docs/example is referenced, but never existed; probably just remove reference
    • remove "examples" and just reference docs/api.md and docs/cli.md as appropriate
  • docs/install.md

    • describe the venv+pip option
    • remove any mention of pyenv (this is not needed for regular users)
    • remove any mention of geomagio (this is for other markdown docs)
    • specify exact version of Python in conda create command (e.g.: "3.11.10")
    • add 'git' to list of packages to include in conda create command. (This seems to be necessary on Windows)
    • replace conda instructions with miniforge.
  • docs/usage.md

    • git-mv docs/usage.md docs/cli.md
    • look for references to docs/usage.md and fix them
    • add more examples
    • reference detailed io and/or algorithm docs if they exist
    • replace "geomag.py" with "geomag-py" in all examples
    • remind users that they need to have "geomagenv" activated before running any apps
  • docs/api.md

    • this document is already about using geomagio module, but needs to make this more clear
    • this document blurs the line with cli.md in places; clean this up
    • add more examples
    • many people consider "api" to be a web service, maybe this needs a new name (?)
  • docs/io/ (folder)

    • this is for docs on factories; we should add to it
  • docs/algorithms/ (folder)

    • this is for docs on algorithms; we should clean, update, add
  • docs/residual/ (folder)

    • this probably belongs inside the docs/algorithms/ folder
  • docs/overview.md

    • I'm not sure this is the best place for this document
    • if we keep it, this doc needs a little updating and cleaning up
  • docs/develop.md

    • modify forking workflow to be consistent with USGS' code.usgs.gov
    • update to reflect use of poetry in (not so) recent versions
    • add or point to separate doc on using Docker for 'local' testing
  • docs/install_docker.md

    • rename, since nothing is about "installing" Docker
    • remove anything about jupyter-notebook server, which doesn't exist AFAIK
    • add something about the data and metadata web services
      • the services themselves might need to be fixed up so that they work for regular users, even if only in a read-only mode
    • add detailed section on using Docker to create local stacks for testing
Edited by Geels, Brendan Ryan