Move to mkdocs from Sphinx

[nh13]

There are a lot of changes required for this PR, most of them minor:

1. Update RST syntax to Markdown (e.g. URLs, anchors to clases/func, code blocks, lists)
2. Make the linter happy (lines too long with new URLs)
3. Consolidate tests (see Package code and tests should be organized in separate directories, to be more consistent with Python conventions #120)
4. Fixed a few other docstring warnings

[nh13]

I would love a review of the live preview. I will admit I am a mkdocs neophyte, so I would welcome pull requests into this branch if you want to noodle on any non-trivial requested changes.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.38%. Comparing base (04c1a9c) to head (6f4e685).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #135   +/-   ##
=======================================
  Coverage   88.38%   88.38%           
=======================================
  Files          16       16           
  Lines        1773     1773           
  Branches      377      377           
=======================================
  Hits         1567     1567           
  Misses        136      136           
  Partials       70       70           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[znorgaard]

I took a quick look at the live preview. Overall, I like the layout and functionality!

Dark Mode

This could be a future enhancement, but a dark mode toggle and defaulting to "auto" to match system settings would be great: https://www.mkdocs.org/user-guide/choosing-your-theme/.

Leftover Styling

I think there's some leftover styling that displays oddly.

There are a handful of ":class:ClassName" instances, example below, but search will find them all.

https://fgpyo--135.org.readthedocs.build/en/135/reference/fgpyo/index.html#fgpyo.fastx.FastxZipped-functions

":py:obj:" seems like a styling leftover too.

https://fgpyo--135.org.readthedocs.build/en/135/reference/fgpyo/index.html#fgpyo.fastx--zipping-fastx-files

Installation Page

Looks like some differences in how to reference page titles.

https://fgpyo--135.org.readthedocs.build/en/135/installation.html

[tfenne]

After poking for a few minutes at the live preview - I like it a lot! I really like:

• That modules are broken into separate pages so you can easily CMD-S and search the text of a module page, and not accidentally scroll into other modules
• I really like the module index that shows up on the right when you click into a module.

Big usability improvement from my perspective.

[tfenne]

I made a quick pass through. Overall I think this is an improvement, but I have several thoughts:

1. Personally I really like the Markdown over RST - I think it's more readable likely less fragile.
2. I think we can and should strike all the "Module Contents" sections from the docs. The right-nav on the module page does a good job of this automatically and we've always struggled to keep these sections up to date as new things get added.
3. I really wish there was a better mechanism for linking to other python symbols vs. including a relative markdown link.
4. The script for auto-discovering modules etc. - I would love for this to be something that is parameterized, and better documented, and then sharable either from fgpyo or as a standalone repo that can be sub-moduled in or something, rather than copy/pasting it between repos.

[tfenne]

I think this is a big step forward on usability of the docs, and maintainability too!

[nh13]

My plan for making the gen_ref_pages.py applicable to all our repos is as follows:

1. Add support for passing arguments to the gen_ref_pages.py in the mkdocs-gen-files repo (PR submitted). We'll need it merged and pushed into a release.
2. Move the gen_ref_pages.py to it's own fulcrumgenomics GitHub repo and start adapting it there.
3. Once we're happy with (2), release it to pypi
4. Once (3) is complete, add (3) as a docs dependency in fgpyo

This may take a little while, but in the meantime I will merge this PR.