@rzetelskik The new version of the theme triggers a warning if an underscore is encountered in a file name. The following files should be renamed to use a hyphen instead of the underscore:

• known_issues
• nodeoperations/automatic_cleanup
• nodeoperations/maintenance_mode
• nodeoperations/replace_node
• nodeoperations/scylla_upgrade
• scylla_cluster_crd

@annastuchlik yup, I've updated the PR just before your comment. Should be fine now.

Let me look into it with @dgarcia360 before I approve or suggest an update. Thanks.

I'm unable to build the docs. It looks like more updates are required to the Makefile. @dgarcia360 Can you provide the details?

I'm unable to build the docs. It looks like more updates are required to the Makefile.

@annastuchlik can you elaborate? What did you try? What do you mean by being unable to build the docs?

I get the following error:

Traceback (most recent call last):
  File "C:\Users\annstu\.poetry\bin\poetry", line 17, in <module>
    from poetry.console import main
ModuleNotFoundError: No module named 'poetry.console'
make: *** [Makefile:24: preview] Error 1

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: rzetelskik, tnozicka

The full list of commands accepted by this bot can be found here.

I get the following error:

Traceback (most recent call last):
  File "C:\Users\annstu\.poetry\bin\poetry", line 17, in <module>
    from poetry.console import main
ModuleNotFoundError: No module named 'poetry.console'
make: *** [Makefile:24: preview] Error 1

@annastuchlik please try the following:

podman run -it --rm -v="$( pwd ):/go/$( go list -m )" --workdir="/go/$( go list -m )/docs" -p 5500:5500 ubuntu:20.04 bash -c 'apt-get update && apt-get install -y curl python3 python3-distutils make git && ./hack/install-poetry.sh && $HOME/.poetry/bin/poetry install && make dirhtml SPHINXOPTS="--keep-going" && make redirects && make preview'

It's what our workflow does essentially.

Hi @annastuchlik, @tnozicka, and @rzetelskik,

While these changes will build the docs as expected for prod, building the docs locally differs from how we do it in other projects. I'm sharing some proposed modifications to the Makefile:

1. Modify the POETRY variable to ensure compatibility for Windows:

   POETRY        = poetry
   
   # For Windows users
   ifeq ($(OS),Windows_NT)
       POETRY = $(APPDATA)\Python\Scripts\poetry
   endif
   

2. Include the setup step before executing commands to generate documentation. For example:

   # Preview commands
   .PHONY: preview
   preview: setup
       $(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
   

   This ensures that the latest version of the dependencies are installed before building the docs.

   If this suggestions don't align with your preferences, I'd like to propose an alternative. To provide more context, I'm sharing a README from another project that outlines their build process, which is different from the one provided by the Sphinx Theme:https://github.com/scylladb/cpp-driver/blob/dacab2ced2fa84d798723d13ecb8c8f658f28d30/README-dev.md

   You could create a similar "README-dev.md" within the docs directory, explaining the considerations needed to run the docs locally. For example:

   # Building the docs
   
   This project uses [Sphinx Theme](https://sphinx-theme.scylladb.com/) , but we have modified the base project to adapt it to our workflows.
   
   ## Local preview
   
   To build the documentation locally, run `make setup` first.
   
   Then, you can build and preview the documentation by following the steps outlined in the [Quickstart guide](https://sphinx-theme.scylladb.com/stable/getting-started/quickstart.html).
   
   ## Custom workflows 
   
   (optional) Explain other  customization. 

@dgarcia360 thanks!
Ad 2. I suppose we could add the setup target and dirhtml/multiversion and redirects as prerequisites for preview and multiversionpreview.
It won't affect our workflow and if it'll align our Makefile with other projects, then I don't see why not. Same goes for Windows compatibility I guess Windows compatibility would require a separate setup script, so I guess a readme saying we don't support it would be good enough.

Having said that, it should go in a separate PR. @tnozicka any objections?

I believe setup shouldn't be a prerequisite to preview (aka) run, nor any of the other targets in the upstream makefile. If you run it a second time, it shouldn't install dependencies again, every time. Separate make invocations give you the option, the is no way to achieve that the other way around. Often times dependency management is left to the user as a common knowledge and not put in the makefile (devs already need to know how to bump the deps).

Adding a README looks reasonable.

I don't mind a windows snippet if the is no other way, but I isn't there something like PATH for windows as well?

@tnozicka @annastuchlik @dgarcia360 please see #1323

/lgtm

With readme shipping in #1323 are there any concerns about the content of this PR or can we land this bump?

With readme shipping in #1323 are there any concerns about the content of this PR or can we land this bump?

I don't think they interfere with each other so I believe they can land in any order.

/lgtm

@rzetelskik @tnozicka Thanks!