[Geoserver-devel] Sphinx upgrades keep breaking the build...

GeoServer GeoServer Developer
,
1

Hi all,
just a couple of weeks ago a Sphinx dependency (pygments) upgrade broke the doc builds, due to syntax highlighting not liking “record” variables (a keyword in Java 17).

Now I’m seeing this, a new upgrade, new issue (as in, new as of this morning):

sphinx:

[echo] Running sphinx-build -D release=2.21-SNAPSHOT -W -b html -d “/home/runner/work/geoserver/geoserver/doc/en/target/user/doctrees” . “/home/runner/work/geoserver/geoserver/doc/en/target/user/html”
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/community/csw-iso/installing.rst:8: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/community/jdbcconfig/installing.rst:8: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/community/jdbcstore/installing.rst:8: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/community/metadata/configuration.rst:14: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/community/taskmanager/user.rst:17: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/configuration/tools/resource/install.rst:10: WARNING: hardcoded link ‘http://geoserver.org/download/’ could be replaced by an extlink (try using ‘:website:download/’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/db2.rst:23: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/h2.rst:13: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/index.rst:17: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/mysql.rst:17: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/oracle.rst:17: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/sqlserver.rst:23: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/database/teradata.rst:131: WARNING: hardcoded link ‘http://geoserver.org/release/stable/’ could be replaced by an extlink (try using ‘:website:release/stable/’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/raster/gdal.rst:27: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/raster/imagepyramid.rst:15: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/raster/index.rst:18: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/vector/featurepregen.rst:11: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/vector/gml.rst:23: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/data/vector/index.rst:19: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/cas/index.rst:14: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/excel.rst:11: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/geofence-server/installing.rst:6: WARNING: hardcoded link ‘https://github.com/geoserver/geoserver/wiki/GSIP-164’ could be replaced by an extlink (try using ‘:wiki:GSIP-164’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/geofence-server/installing.rst:15: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/geofence/installing.rst:6: WARNING: hardcoded link ‘https://github.com/geoserver/geoserver/wiki/GSIP-164’ could be replaced by an extlink (try using ‘:wiki:GSIP-164’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/geofence/installing.rst:17: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/importer/installing.rst:6: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/inspire/installing.rst:6: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/mapml/index.rst:16: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/mongodb/index.rst:12: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/monitoring/installation.rst:12: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/extensions/vectortiles/install.rst:6: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/linux.rst:17: WARNING: hardcoded link ‘http://geoserver.org/release/stable’ could be replaced by an extlink (try using ‘:website:release/stable’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/osx_binary.rst:17: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/osx_binary.rst:19: WARNING: hardcoded link ‘http://geoserver.org/release/stable’ could be replaced by an extlink (try using ‘:website:release/stable’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/war.rst:18: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/win_binary.rst:18: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/win_binary.rst:20: WARNING: hardcoded link ‘http://geoserver.org/release/stable’ could be replaced by an extlink (try using ‘:website:release/stable’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/win_installer.rst:14: WARNING: hardcoded link ‘http://geoserver.org/download’ could be replaced by an extlink (try using ‘:website:download’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/installation/win_installer.rst:16: WARNING: hardcoded link ‘http://geoserver.org/release/stable’ could be replaced by an extlink (try using ‘:website:release/stable’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/introduction/gettinginvolved.rst:24: WARNING: hardcoded link ‘http://docs.geoserver.org/latest/en/docguide/quickfix.html’ could be replaced by an extlink (try using ‘:docguide:quickfix.html’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/introduction/gettinginvolved.rst:82: WARNING: hardcoded link ‘http://geoserver.org/support/’ could be replaced by an extlink (try using ‘:website:support/’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/services/wps/install.rst:8: WARNING: hardcoded link ‘http://geoserver.org/download/’ could be replaced by an extlink (try using ‘:website:download/’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/styling/workshop/setup/install.rst:26: WARNING: hardcoded link ‘http://geoserver.org/download/’ could be replaced by an extlink (try using ‘:website:download/’ instead)
[exec] /home/runner/work/geoserver/geoserver/doc/en/user/source/tutorials/palettedimage/palettedimage.rst:138: WARNING: hardcoded link ‘http://geoserver.org/download/attachments/1278244/nyp.pal?version=1’ could be replaced by an extlink (try using ‘:website:download/attachments/1278244/nyp.pal?version=1’ instead)

This is becoming a chore, and causing friction with un-related changes… it’s caused by:

  • Github builds picking the latest sphinx at every run (and all its deps along with it)
  • Build setup to fail on warnings
    Maybe we should pin the Sphinx build to a specific version… but sometimes it’s the dependencies that seem to be causing the issue here.

About the warnings above… what do you want to do?
I’ve been looking for this :website: directive in the Sphinx official docs, cannot find it…

···

Regards,

Andrea Aime

==
GeoServer Professional Services from the experts!

Visit http://bit.ly/gs-services-us for more information.

Ing. Andrea Aime
@geowolf
Technical Lead

GeoSolutions Group
phone: +39 0584 962313

fax: +39 0584 1660272

mob: +39 333 8128928

https://www.geosolutionsgroup.com/

http://twitter.com/geosolutions_it

Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia.

This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail

2

Hmm, I can’t seem to get a doc build at all on my local machine! I think we want to keep warnings on since RST is so prone to breaking on typos and spacing issues which it only flags as warnings. So if we can fix the sphinx and dependency versions then that would be easiest.

Ian

···

Ian Turton

3

That is great, annoying right now - but very handy to track down external links. I will take care of fixing the above warnings; since I am the person who likes external links :slight_smile:

Just need to figure out what version of sphinx-build is being used…

···

–
Jody Garnett

4

That is great, annoying right now - but very handy to track down external links. I will take care of fixing the above warnings; since I am the person who likes external links :slight_smile:

Good, thanks!

Just need to figure out what version of sphinx-build is being used…

I can help here, it’s the one that has been released… this morning!
Version 4.4.0, release Jan 17h, see: https://www.sphinx-doc.org/en/master/changes.html
I’m not entirely sure the issue triggers due to Sphinx, or one of its dependencies, though…

Cheers
Andrea

···

GeoServer Professional Services from the experts!

Visit http://bit.ly/gs-services-us for more information.

Ing. Andrea Aime
@geowolf
Technical Lead

GeoSolutions Group
phone: +39 0584 962313

fax: +39 0584 1660272

mob: +39 333 8128928

https://www.geosolutionsgroup.com/

http://twitter.com/geosolutions_it

Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia.

This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail

5

Hmm, I can’t seem to get a doc build at all on my local machine!

Here I run pypi, e…g:

pip install --upgrade Sphinx

Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: Sphinx in /home/aaime/.local/lib/python3.8/site-packages (4.2.0)
Collecting Sphinx
Downloading Sphinx-4.4.0-py3-none-any.whl (3.1 MB)

████████████████████████████████| 3.1 MB 4.7 MB/s

Hum… uh oh, what have I done… ah yep, this upgrade broke the Sphinx build locally too LOL,
same errors found in the Github checks…

Cheers
Andrea

···

GeoServer Professional Services from the experts!

Visit http://bit.ly/gs-services-us for more information.

Ing. Andrea Aime
@geowolf
Technical Lead

GeoSolutions Group
phone: +39 0584 962313

fax: +39 0584 1660272

mob: +39 333 8128928

https://www.geosolutionsgroup.com/

http://twitter.com/geosolutions_it

Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia.

This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail

6

Here is a PR to get our build back: https://github.com/geoserver/geoserver/pull/5593

In reviewing extension install instructions I noticed we still had a page for gml datastore.

···

–
Jody Garnett