Comments (8)
@maneelusf @devendragovil what is the udpate on this issue?
from toponetx.
@maneelusf @devendragovil what is the update on this?
from toponetx.
A major update on this issue:
Update
There are over 250 warnings that are being thrown during the docs build process mostly because the function/method docstrings haven't been written to be compliant with numpydoc. I have been trying to resolve these, but in a lot of cases I think the original method creator can help resolve the issues better.
Further Issues
Due to the docstring parsing warnings, the docs generated by sphinx are not complete or correct.
An example: If the docstring section in a method begins with Return
instead of Returns
, sphinx doesn't parse it any longer as the Returns section and skips generating the returns section for the final doc.
Solution
I think two steps are needed:
- We need to manually resolve the warnings that are already being thrown (around 250 of them for this package)
- We need to make necessary changes in the pre-commit and CI/CD workflows to make sure that docs are generated correctly from now onwards.
from toponetx.
I am working on amending the pre-commit file and the CI/CD workflow to incorporate docstring checks.
from toponetx.
the CI/CD workflow to incorporate docstring checks
We have validation since #297, but I think the checks do not fail for warnings
from toponetx.
@ffl096 If I understand it correctly, the check has been placed as the part of the sphinx build process by specifying numpydoc validation in the conf.py file read by Sphinx.
I think we may want to add the check in the CI/CD workflow explicitly.
from toponetx.
Why? It is part of the CI/CD workflow this way as well. Not sure why we should spread doc-related validations across different places instead of everything in sphinx.
from toponetx.
I would argue that this isn't a doc related validation, but more so related to codebase i.e. the docstrings format.
However, the more important goal should be to fail a CI/CD workflow so as to incentivize correct docstring formatting something akin to compliance with PEP8.
from toponetx.
Related Issues (20)
- Inconsistencies in `__getitem__` implementation across complex types
- Naming inconsistency: attributes vs. properties
- Inconsistencies in `__contains__` implementation across complex types HOT 2
- BUG in get_rank method in ColoredHyperEdgeView HOT 2
- Edge features of COSEG is a list of lists
- Edge Features of COSEG
- remove_singletons in ColoredHyperGraph throws error. HOT 2
- Unreachable code in ColoredHyperGraph, ColoredHyperGraphView, and CombinatorialComplex
- Switch from sparse matrices to sparse arrays
- Add `CITATION.cff` file after JMLR submission
- Breaking downstream change HOT 3
- Clarification of order-preserving rule for CCC HOT 1
- Definition of CCC and the logic that follows from it. HOT 11
- Package is breaking because of python version 3.12.0 HOT 2
- pyproject.toml not enforcing build constraints
- Docstrings Missing HOT 1
- Changing lint and formatter HOT 6
- Import Convention for TopoNetX HOT 1
- Invalid return type for disconnected elements in `algorithms.distance` module
- OFF files to NPZ files
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from toponetx.