Building the docs

[Lukas Ewecker]

🐛 Bug

I am trying to build the docs. When running make docs, I get the first error:

ERROR: Double requirement given: transformers<4.40.0,>4.4.0 (from -r requirements/text.txt (line 7)) (already in transformers<4.40.0,>=4.10.0 (from -r requirements/multimodal.txt (line 4)), name='transformers')

I fixed this by commenting out the transformers >4.4.0, <4.40.0 requirement in requirements/text.txt.

Next, it is difficult to figure out how to install the lai-sphinx-theme package. I fixed this by looking at the pytorch-lightning Makefile:

pip install -q awscli
mkdir -p dist/
aws s3 sync --no-sign-request s3://sphinx-packages/ dist/
pip install lai-sphinx-theme -f dist/

Now, I get a sphinx error when running make docs (i tried both Python 3.8 and 3.10, with the same result):

# clean all temp runs
rm -rf 
rm -rf _ckpt_*
rm -rf .mypy_cache
rm -rf .pytest_cache
rm -rf tests/.pytest_cache
rm -rf ./docs/build
rm -rf ./docs/source/generated
rm -rf ./docs/source/*/generated
rm -rf ./docs/source/api
rm -rf build
rm -rf dist
rm -rf *.egg-info
rm -rf src/*.egg-info
pip install -e . --quiet -r requirements/_docs.txt
# apt-get install -y texlive-latex-extra dvipng texlive-pictures texlive-fonts-recommended cm-super
TOKENIZERS_PARALLELISM=false python -m sphinx -b html -W --keep-going docs/source docs/build
Running Sphinx v5.3.0

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

Traceback (most recent call last):
  File "/home/lukas/Development/pycharm_workspace/torchmetrics/venv/lib/python3.8/site-packages/sphinx/config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "/home/lukas/Development/pycharm_workspace/torchmetrics/docs/source/conf.py", line 95, in <module>
    adjust_linked_external_docs(
  File "/home/lukas/Development/pycharm_workspace/torchmetrics/venv/lib/python3.8/site-packages/lightning_utilities/docs/formatting.py", line 160, in adjust_linked_external_docs
    lines = fopen.readlines()
  File "/usr/lib/python3.8/codecs.py", line 322, in decode
    (result, consumed) = self._buffer_decode(data, self.errors, final)
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa4 in position 64: invalid start byte

make: *** [Makefile:34: docs] Error 2

To Reproduce

1. Clone the repo
2. Run make docs

Expected behavior

No errors

Environment

• TorchMetrics version: master at d6b5b98
• Python & PyTorch Version (e.g., 1.0): I tried both Python 3.8 and Python 3.10
• Any other relevant information such as OS (e.g., Linux): Ubuntu 20.04

[Jirka Borovec]

Hello, thank you for your interest and sorry that your local docs build does not work...
Just checked master status, and seems it works fine there, so wondering what is different to your env, pls check https://github.com/Lightning-AI/torchmetrics/actions/runs/8522325272/job/23342284976

[Lukas Ewecker]

I inspected the the action logs and it seems that you use a different way to build the docs there than stated in CONTRIBUTING.md. There, it says to do the following:

torchmetrics/.github/CONTRIBUTING.md

Lines 112 to 120 in d6b5b98

 When updating the docs make sure to build them first locally and visually inspect the html files (in the browser) for 
 formatting errors. In certain cases, a missing blank line or a wrong indent can lead to a broken layout. 
 Run these commands 
  
 ```bash 
 make docs 
 ``` 
  
 and open `docs/build/html/index.html` in your browser. 

This results in the error posted above.

However, in your action, you do:

cd docs
make html --debug --jobs $(nproc) SPHINXOPTS="-W --keep-going"

This seems to work for me locally.