Fix documentation building

[ziatdinovmax]

The documentation builds are failing seemingly because we no longer have __version__.py file.

Running Sphinx v6.2.1

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/checkouts/latest/docs/source/conf.py", line 28, in <module>
    with open(os.path.join(module_dir, '../../gpax/__version__.py')) as f:
FileNotFoundError: [Errno 2] No such file or directory: '/home/docs/checkouts/readthedocs.org/user_builds/gpax/checkouts/latest/docs/source/../../gpax/__version__.py'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/application.py", line 207, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 177, in read
    namespace = eval_config_file(filename, tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 367, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/checkouts/latest/docs/source/conf.py", line 28, in <module>
    with open(os.path.join(module_dir, '../../gpax/__version__.py')) as f:
FileNotFoundError: [Errno 2] No such file or directory: '/home/docs/checkouts/readthedocs.org/user_builds/gpax/checkouts/latest/docs/source/../../gpax/__version__.py'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/envs/latest/lib/python3.9/site-packages/sphinx/config.py", line 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/docs/checkouts/readthedocs.org/user_builds/gpax/checkouts/latest/docs/source/conf.py", line 28, in <module>
    with open(os.path.join(module_dir, '../../gpax/__version__.py')) as f:
FileNotFoundError: [Errno 2] No such file or directory: '/home/docs/checkouts/readthedocs.org/user_builds/gpax/checkouts/latest/docs/source/../../gpax/__version__.py'

Should be an easy fix.

[matthewcarbone]

@ziatdinovmax oof I guess my new build methods broke that.

As long as we substitute the correct version in at _version.py and read from that I think this should work. The problem is here:

# The full version, including alpha/beta/rc tags
module_dir = os.path.dirname(os.path.abspath(__file__))
with open(os.path.join(module_dir, '../../gpax/__version__.py')) as f:
    release = f.read().split("'")[1]

I might have overlooked this. I see you're using readthedocs to build the documentation. When I've done this in the past I build the whole project first, then build the docs (so the _version.py file is hardcoded already). Might require some hacks to fix but hopefully straightforward.

Actually it should be really straightforward, but we might have to execute part of the build script before building the docs. Looks like this can be accomplished: https://docs.readthedocs.io/en/stable/config-file/v2.html#build-jobs.

Full possible fix

Assuming readthedocs uses vcs and checks out to the repository, this _should_work, I would think... but I'm not sure how to test it locally.

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.9"
  jobs:
    pre_create_environment:
      - echo "__version__ = '$(dunamai from any --style=pep440 --no-metadata)'" >gpax/_version.py

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/source/conf.py

# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF and ePub
formats: []

# Optionally set the version of Python and requirements required to build your docs
python:
  install:
    - requirements: docs/requirements_rtd.txt

[sagarsadhu]

Hi @matthewcarbone,

I am trying to contribute to opensource projects. Found this issue. Able to fix this issue by adding dunamai in docs requirements, importing the version variable from gpax/_version.py file and then I was able to generate the docs.

Please let me know if I can go ahead and create a PR for the same.

Regards,
Sagar

[matthewcarbone]

@sagarsadhu that sounds a lot cleaner than what I suggested! Go for it!

[sagarsadhu]

created the PR with changes.

#113

[ziatdinovmax]

@sagarsadhu - thanks!