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

assigned to @swilbur

assigned to @erigler and unassigned @swilbur

I re-assigned this to myself. The documentation is in worse condition than I remembered, and I think I might need to give this some dedicated thought and effort. I might peel off sub-tasks and assign them to others.

changed the description

changed title from Bad links in Readme.md to Documentation cleanup needed

mentioned in merge request !285 (merged)

Just letting @bgeels and @awernle know about this "umbrella" issue.

NOTE: I reached out to the chs support portal to ask about the "Service Desk" option for code.usgs.gov. They were surprisingly receptive, and are currently looking into possible technical limitations, but there do not appear to be any bureaucratic hurdles. Not likely to happen in 2023 though.

I often see a "contributions" document in large public repos on github. These provides guidelines for external collaborators to submit changes.

That is definitely worth pursuing.

Something to keep in mind: the only way for outside collaborators to contribute actual merge requests to the project is to have an account on code.usgs.gov. Getting that account is a little arduous, but certainly doable for a committed collaborator. But it does place an unfortunate bottleneck on what we would like to be an "open" project.

added Discuss label

changed the description

marked the checklist item remove any mention of pyenv (this is not needed for regular users) as completed

marked the checklist item remove any mention of geomagio (this is for other markdown docs) as completed

marked the checklist item remove any mention of geomagio (this is for other markdown docs) as incomplete

marked the checklist item remove any mention of pyenv (this is not needed for regular users) as incomplete