Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add pydocsstyle linting and switch to mkdocs #396

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

kenibrewer
Copy link
Member

@kenibrewer kenibrewer commented Apr 3, 2024

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
Copy link

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.

@kenibrewer kenibrewer changed the title docs: add pydocsstyle linting and update docstrings docs: add pydocsstyle linting and switch to mkdocs Apr 25, 2024
@kenibrewer kenibrewer force-pushed the docs/add-docs-build-checks branch 2 times, most recently from 000ec37 to 4f728ef Compare April 25, 2024 23:43
@kenibrewer kenibrewer marked this pull request as ready for review April 26, 2024 12:10
Copy link
Member

@d33bs d33bs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this file still required in order to use mkdocs?

pyproject.toml Show resolved Hide resolved
Comment on lines +177 to +178
# Disable docstring checks in tests
"D",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@echo "📚 Building documentation"
@poetry run sphinx-build docs build
@echo "📚 Serving documentation"
@mkdocs serve
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

setup-poetry: true
install-deps: true
- name: Build documentation
run: poetry run mkdocs build --strict
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gwaybio
Copy link
Member

gwaybio commented Oct 19, 2024

@kenibrewer - checking in on this PR. Do you think you'll be able to resolve conflicts andrevisit @d33bs review? It would be great to include this in the patch release #461 if possible!

@kenibrewer
Copy link
Member Author

@d33bs @gwaybio I'm a bit swamped a the moment preparing for the Nextflow summit next week. So probably not a good idea to wait on me for this patch. I'll try to get to it when sometime when I have after the Summit though!

@gwaybio
Copy link
Member

gwaybio commented Oct 23, 2024

No worries! Thanks for the heads up

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants