docs: add pydocsstyle linting and switch to mkdocs #396

kenibrewer · 2024-04-03T01:43:04Z

Description

I was working on #382 and couldn't figure out how to resolve some sphinx build errors with opaque error messages. I decided to take this opportunity to switch our docs engine to mkdocs instead.

Enables pydocstrings linting checks
Various documentation strings changes to conform with linting checks.
Switch from Sphinx to Mkdocs
Added docs build ci check

What is the nature of your change?

Bug fix (fixes an issue).
Enhancement (adds functionality).
Breaking change (fix or feature that would cause existing functionality to not work as expected).
This change requires a documentation update.

Checklist

Please ensure that all boxes are checked before indicating that a pull request is ready for review.

I have read the CONTRIBUTING.md guidelines.
My code follows the style guidelines of this project.
I have performed a self-review of my own code.
I have commented my code, particularly in hard-to-understand areas.
I have made corresponding changes to the documentation.
My changes generate no new warnings.
New and existing unit tests pass locally with my changes.
I have added tests that prove my fix is effective or that my feature works.
I have deleted all non-relevant text in this pull request template.

📚 Documentation preview 📚: https://pycytominer--396.org.readthedocs.build/en/396/

codecov-commenter · 2024-04-03T01:51:46Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.72%. Comparing base (3286270) to head (059267f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #396   +/-   ##
=======================================
  Coverage   94.72%   94.72%           
=======================================
  Files          56       56           
  Lines        3147     3147           
=======================================
  Hits         2981     2981           
  Misses        166      166

Flag	Coverage Δ
unittests	`94.72% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

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

d33bs

Nice job! I left a few comments and suggestions throughout. Some of this touched on docstring content updates as there were minor updates applied to these in certain spots.

Additionally, I'm wondering if we need to update the CONTRIBUTING.md docs on documentation (very meta 🙂 ). Currently these make mention of Sphinx tooling and procedures.

d33bs · 2024-04-26T14:02:27Z

docs/README.md

+The software [morpheus](https://software.broadinstitute.org/morpheus/) enables profile visualization in the form of interactive heatmaps.
+Pycytominer can convert profiles into a `.gct` file for drag-and-drop input into morpheus.
+
+```python


I noticed in the Read the Docs preview that these Python code blocks don't appear to include syntax highlighting. Is it possible to enable this somehow?

d33bs · 2024-04-26T14:04:05Z

README.md

Would this become a duplicate of the content found at the root of the project? If so, is there a way we could dynamically reference the root readme without having to create a duplicate here? I can see how differentiating here might be a good idea, but if the content is a clone, it could be difficult to keep up to date over time (even minor skew here could be confusing to readers).

d33bs · 2024-04-26T14:06:15Z

.readthedocs.yml

+    - git fetch --unshallow || true
+    # Install poetry
+    # https://python-poetry.org/docs/#installing-manually
+    - pip install poetry


This might be an external issue: reading through this line and recognizing poetry as a dependency which manages other dependencies, would it make sense to declare the version range acceptable for this and other installations?

.github/workflows/integration-test.yml

d33bs · 2024-04-26T14:09:43Z

docs/conf.py

Is this file still required in order to use mkdocs?

pyproject.toml

d33bs · 2024-04-26T16:23:29Z

pyproject.toml

+    # Disable docstring checks in tests
+    "D",


Would it make sense to address this eventually? I can understand how it might be a big task to account for this, but feel it may be healthy to document tests at a certain level (otherwise we may set the precedent that we don't need to explain tests for others).

d33bs · 2024-04-26T16:27:20Z

tests/test_normalize.py

@@ -84,7 +84,7 @@ def test_normalize_standardize_allsamples():
    Testing normalize pycytominer function
    method = "standardize"
    meta_features = None
-    samples="all"
+    samples="all".


These changes which add the period at the end of method specification felt a little off, and made me wonder about the value-add of these changes. I'd suggest rolling back these changes unless there's a compelling reason to keep them. I also wasn't sure more generally: was the ruff configuration supposed to ignore testing docstrings?

d33bs · 2024-04-26T16:29:38Z

Makefile

-	@echo "📚 Building documentation"
-	@poetry run sphinx-build docs build
+	@echo "📚 Serving documentation"
+	@mkdocs serve


Would it still make sense to run the build or serve through poetry?

d33bs · 2024-04-26T16:31:44Z

.github/workflows/integration-test.yml

+          setup-poetry: true
+          install-deps: true
+      - name: Build documentation
+        run: poetry run mkdocs build --strict


Is there a way to build this check into a pre-GH-Actions check so developers can avoid surprising results from possible failures here? Mostly I wonder here if there's a pre-commit check which could be included that runs a check that things are prepared in advance.

kenibrewer and others added 3 commits April 2, 2024 23:37

docs: adjust docstrings for pydocstyle

c1d2138

docs: format ipynb with ruff

eb8a886

docs: correct docstring style checks

059267f

Merge branch 'main' into docs/add-docs-build-checks

51a9f8a

kenibrewer changed the title ~~docs: add pydocsstyle linting and update docstrings~~ docs: add pydocsstyle linting and switch to mkdocs Apr 25, 2024

kenibrewer force-pushed the docs/add-docs-build-checks branch 2 times, most recently from 000ec37 to 4f728ef Compare April 25, 2024 23:43

docs: initial mkdocs conversion

54730fc

kenibrewer force-pushed the docs/add-docs-build-checks branch from 4f728ef to 54730fc Compare April 25, 2024 23:49

kenibrewer added 2 commits April 26, 2024 12:03

docs: incorporate walkthrough w/ mkdocs-jupyter

14f78a2

ci: add docs build check

8aae6dd

kenibrewer force-pushed the docs/add-docs-build-checks branch from 6b83770 to 8aae6dd Compare April 26, 2024 12:09

kenibrewer requested review from axiomcura, shntnu, d33bs and gwaybio April 26, 2024 12:10

kenibrewer marked this pull request as ready for review April 26, 2024 12:10

d33bs reviewed Apr 26, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add pydocsstyle linting and switch to mkdocs #396

docs: add pydocsstyle linting and switch to mkdocs #396

kenibrewer commented Apr 3, 2024 •

edited

codecov-commenter commented Apr 3, 2024

d33bs left a comment

d33bs Apr 26, 2024

d33bs Apr 26, 2024

d33bs Apr 26, 2024

d33bs Apr 26, 2024

d33bs Apr 26, 2024

d33bs Apr 26, 2024

d33bs Apr 26, 2024

d33bs Apr 26, 2024

docs: add pydocsstyle linting and switch to mkdocs #396

Are you sure you want to change the base?

docs: add pydocsstyle linting and switch to mkdocs #396

Conversation

kenibrewer commented Apr 3, 2024 • edited

Description

What is the nature of your change?

Checklist

codecov-commenter commented Apr 3, 2024

Codecov Report

d33bs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kenibrewer commented Apr 3, 2024 •

edited