tripal / tripal_doc

Official Documentation for the Tripal Platform
https://tripaldoc.readthedocs.io/en/latest/
GNU General Public License v3.0
2 stars 3 forks source link

Fix Failing readthedoc builds #48

Closed laceysanderson closed 7 months ago

laceysanderson commented 7 months ago

Issue #47

Our documentation is currently failing to build in readthedocs.org. This is because they have deprecated config through the UI and now require a .readthedocs.yaml config file instead which we do not have...

See https://blog.readthedocs.com/migrate-configuration-v2/ for more detail.

This PR adds this configuration file and also fixes some warning that have snuck into our build process over the year. Additionally it upgrades the Dockerfil to a newer version of python to match the readthedocs environment.

Specific build warnings fixed:

/tripal_doc/docs/admin_guide.rst:5: WARNING: toctree contains reference to nonexisting document 'admin_guide/drupal'
/tripal_doc/docs/admin_guide/jobs.rst:14: WARNING: duplicate label overview, other instance in /tripal_doc/docs/admin_guide/jobs.rst
/tripal_doc/docs/design/overview.rst:2: WARNING: duplicate label overview, other instance in /tripal_doc/docs/admin_guide/jobs.rst
/tripal_doc/docs/design/pending/entities-fields/overview.rst:2: WARNING: duplicate label design summary, other instance in /tripal_doc/docs/design/pending/biodb/design.rst
/tripal_doc/docs/design/standards/contributing.rst:14: WARNING: duplicate label design documentation, other instance in /tripal_doc/docs/design.rst
/tripal_doc/docs/dev_guide/lessons.rst:3: WARNING: duplicate label hands-on training, other instance in /tripal_doc/docs/dev_guide/cvterms.rst
/tripal_doc/docs/install/requirements.rst:3: WARNING: duplicate label requirements, other instance in /tripal_doc/docs/design/pending/entities-fields/requirements.rst
/tripal_doc/docs/sitebuilding_guide.rst:5: WARNING: toctree contains reference to nonexisting document 'site_building/organism_example'
/tripal_doc/docs/sitebuilding_guide.rst:5: WARNING: toctree contains reference to nonexisting document 'site_building/loading_content'
/tripal_doc/docs/dev_guide/cvterms.rst:70: WARNING: unknown document: '/dev_guide/lessons/create_cvterms'

This means none of the changes merged since September 25, 2023 are not showing up at https://tripaldoc.readthedocs.io/en/latest/index.html

Testing

  1. Go to the docs for this specific branch and confirm they built correctly: https://tripaldoc.readthedocs.io/en/47-our-docs-build-is-currently-failing/. Specifically check
    • admin guide content listing
    • admin guide > jobs
    • site building guide content listing
  2. Go to https://readthedocs.org/projects/tripaldoc/builds/ and confirmed the most recent build on this branch Passed
  3. Build the docs locally using the instructions in the README and confirm they build without any errors.
  4. Build the docker locally using docker build --tag=local/tripaldoc:latest ./ and confirm it builds without error.

Firefox_Screenshot_2023-11-30T01-53-36 436Z

laceysanderson commented 7 months ago

Awesome! Thank you @dsenalik ❤️ 🎉

dsenalik commented 7 months ago

Thanks for fixing this - I'm sorry I didn't notice!