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

Fix warnings in building of documentation #226

Merged
merged 3 commits into from
Jun 17, 2024
Merged

Fix warnings in building of documentation #226

merged 3 commits into from
Jun 17, 2024

Conversation

kklein
Copy link
Collaborator

@kklein kklein commented Jun 17, 2024

The rendered version of this PR can be found here.

Status quo

When running make html in datajudge/docs on main, 178 warnings are produced with sphinx 7.3.7.

Few of those warnings are indeed desired in that they hint at problems we'd want to fix, e.g. :

Assertion Message Styling
----------------
/Users/kevinklein/Code/datajudge/docs/source/getting_started.rst:136: WARNING: Title underline too short.

Assertion Message Styling
----------------
/Users/kevinklein/Code/datajudge/docs/source/testing.rst:2: WARNING: Duplicate explicit target name: "here".

Yet, the bulk of the warnings is of one of two forms:

  • /Users/kevinklein/Code/datajudge/src/datajudge/requirements.py:docstring of datajudge.requirements.Requirement:19: WARNING: autosummary: stub file not found 'datajudge.Requirement.append'. Check your autosummary_generate setting.
  • /Users/kevinklein/Code/datajudge/src/datajudge/requirements.py:docstring of datajudge.requirements.Requirement.insert:21: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Proposed changes

  • Address the warnings we'd like to receive in 42f8a50.
  • Adapt the configuration of our documentation in 42f8a50.
    • The autosummary: stub file not found 'datajudge.Requirement.append'. Check your autosummary_generate setting. warnings are eliminated by inheriting doc strings for non-overwritten methods from parent classes.
    • The Explicit markup ends without a blank line; unexpected unindent. warnings are eliminated for a reason that's clear to me.

Running make html on this branch creates no more warnings.

Remarks

In order to address the Explicit markup ends without a blank line; unexpected unindent. warnings, I tried adaptations of the doc strings suggested in this stackoverflow thread. Unfortunately it didn't resolve the issue at hand.

@kklein kklein force-pushed the fix_docs_warnings branch from d77cbe1 to 8aa51dd Compare June 17, 2024 08:48
@kklein kklein marked this pull request as ready for review June 17, 2024 09:06
@kklein kklein requested review from 0xbe7a and ivergara June 17, 2024 09:06
@kklein kklein added the ready label Jun 17, 2024
@kklein kklein merged commit c52ad81 into main Jun 17, 2024
50 checks passed
@kklein kklein deleted the fix_docs_warnings branch June 17, 2024 20:33
kklein added a commit that referenced this pull request Jun 25, 2024
* Address doc-building warnings.

* Adapt configuration.
kklein added a commit that referenced this pull request Jun 25, 2024
* Address doc-building warnings.

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

Successfully merging this pull request may close these issues.

2 participants