Docs - Strive for a clean build log

[echedey-ls]

Running:

solposx\docs> sphinx-build -b linkcheck --nitpicky source build  
Running Sphinx v8.2.3

Relevant warnings and errors:

Unused footnotes in a docstring

\solposx\src\solposx\solarposition\skyfield.py:docstring of solposx.solarposition.skyfield.skyfield:30: WARNING: Footnote [1] is not referenced. [ref.footnote]
\solposx\src\solposx\solarposition\skyfield.py:docstring of solposx.solarposition.skyfield.skyfield:32: WARNING: Footnote [2] is not referenced. [ref.footnote]
\solposx\venv\Lib\site-packages\pvlib\solarposition.py:docstring of pvlib.solarposition.spa_python:55: WARNING: Footnote [2] is not referenced. [ref.footnote]

Inexistent objects linked:

\solposx\src\solposx\solarposition\michalsky.py:docstring of solposx.solarposition.michalsky.michalsky:50: WARNING: py:func reference target not found: pandas.DatetimeIndex.to_julian_date 
[ref.func]

Upstream fix is pending via pandas-dev/pandas#62090

\solposx\src\solposx\solarposition\nasa_horizons.py:docstring of solposx.solarposition.nasa_horizons.nasa_horizons:25: WARNING: py:const reference target not found: URL

I propose making this docstring a formatted f-string (excuse the redundancy) and just show it. I.e.:
in src\solposx\solarposition\nasa_horizons.py,
url : str, optional API endpoint. The default is ``{URL}``.

[AdamRJensen]

\solposx\src\solposx\solarposition\nasa_horizons.py:docstring of solposx.solarposition.nasa_horizons.nasa_horizons:25: WARNING: py:const reference target not found: URL

I propose making this docstring a formatted f-string (excuse the redundancy) and just show it. I.e.: in src\solposx\solarposition\nasa_horizons.py, url : str, optional API endpoint. The default is{URL}.

It seems that Python doc string have to be literals and can't be f-formatted strings. Anyhow, I've just pasted in the url to the docs.

[AdamRJensen]

Unused footnotes in a docstring

\solposx\src\solposx\solarposition\skyfield.py:docstring of solposx.solarposition.skyfield.skyfield:30: WARNING: Footnote [1] is not referenced. [ref.footnote]
\solposx\src\solposx\solarposition\skyfield.py:docstring of solposx.solarposition.skyfield.skyfield:32: WARNING: Footnote [2] is not referenced. [ref.footnote]
\solposx\venv\Lib\site-packages\pvlib\solarposition.py:docstring of pvlib.solarposition.spa_python:55: WARNING: Footnote [2] is not referenced. [ref.footnote]

The spa was fixed in pvlib/pvlib-python#2523 and the skyfield instances were fixed in #87.

Once a new pvlib version comes out with the new fix, I plan on setting fail_on_warning to True, which would force such things to be fixed:

solposx/.readthedocs.yml

Line 8 in ebe5a0c

fail_on_warning: false

[echedey-ls]

You're right about the f-strings.

Maybe this package should have it's own version of pvlib's spa to avoid a mismatch between it's docs and whatever version a user may install as dependency of solposx. Right now, any plain install without any optional deps allows any pvlib version to be installed. However, the docs optional deps [in pyproject.toml] pins pvlib to 0.13.0. The latter must also be set to latest to allow for those changes to take effect.

Just removing the docs pvlib==0.13.0 would be enough to ensure using the latest. But, personally, I find it a bit cumbersome to depend on a third package for it's own docstrings. Less control, and no file related to the algorithm. Friendly objection that if this package wants to be a flagship in solpos algorithms, it should be easy to find the Python implementations. Having a findable file in the repo is a must for me. Optionally, the "See source" button in the right sidebar could be set up.