Remove useless griffe type/annotation warnings in upgrade.sh

[markkuleinio]

NetBox version

v4.3.1

Feature type

Change to existing functionality

Proposed functionality

I'm proposing ignoring the "No type or annotation" warnings from griffe (mkdocs build) outputs in upgrade.sh.

It can be done by replacing the current

COMMAND="mkdocs build"

with

COMMAND="mkdocs build 2> >(grep -v 'No type or annotation for parameter')"

Output of that section after the change:

Building documentation (mkdocs build 2> >(grep -v 'No type or annotation for parameter'))...
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /opt/netbox/netbox/project-static/docs
INFO    -  Documentation built in 10.11 seconds

(= there are no type/annotation warnings anymore)

AFAIK, there is no way to suppress those natively in griffe while still keeping the INFO level outputs. (In mkdocs build there is a "-q, --quiet: Silence warnings" option but it silences everything, not just warnings. Since the run takes that long, I believe the full mute is not feasible here.)

Alternatively, types or annotations could be added in the NetBox source files+parameters shown in the griffe warnings. This solution above could still be implemented as a fast solution while the type/annotation addition is in the works.

Use case

When running upgrade.sh, in the "Building documentation (mkdocs build)..." phase, there are 60+ lines of this kind of output:

WARNING - griffe: netbox/netbox/jobs.py:50: No type or annotation for parameter 'job'
WARNING - griffe: netbox/netbox/jobs.py:143: No type or annotation for parameter 'instance'
WARNING - griffe: netbox/netbox/jobs.py:144: No type or annotation for parameter 'schedule_at'
WARNING - griffe: netbox/netbox/jobs.py:145: No type or annotation for parameter 'interval'
...

It distracts the NetBox administrator running the upgrade.sh task when upgrading NetBox, and does not provide any meaningful or actionable outputs for the administrator.

Database changes

None

External dependencies

None (upgrade.sh already requires bash and grep, and the redirection syntax is working with bash)

[mr1716]

The other option would be to add said information so the results dont show up. But not sure how that would be done nor if even worth it

[jeremystretch]

Simply suppressing the output is not a valid solution: The root cause must be identified and addressed. I'll mark this as open for a volunteer but please note that only a proper fix will be considered.

[AlexandreLanglade]

Hi

1. If interested in it, I've found a 3 years old issue about ignoring unwanted warnings in the mkdocs project (here)

2. About the cause here, that's what I suspect :

I take the first warning as the exemple WARNING - griffe: netbox/netbox/jobs.py:50: No type or annotation for parameter 'job'
but the cause should be identical for the 60 lines.

This is the current code's doc 'missing' type or annotation :
netbox/netbox/jobs.py

    def __init__(self, job):
        """
        Args:
            job: The specific `Job` this `JobRunner` is executing.
        """
        self.job = job

• Fix 1 :
  Example Google Style Python Docstrings

   Args:
       param1 (int): The first parameter.
       param2 (str): The second parameter.

⬇️​

   Args:
       job (Job): The specific `Job` this `JobRunner` is executing.

• or Fix 2 :
  type hints doc

def surface_area_of_cube(edge_length: float):
   ...

⬇️​

def __init__(self, job: Job):
   ...