Make poetry a prerequisite #307
Comments
This was referenced Feb 9, 2022
avikivity
added a commit
to scylladb/scylladb
that referenced
this issue
Feb 10, 2022
Related issue scylladb/sphinx-scylladb-theme#310 ScyllaDB Sphinx Theme 1.1 is now released 🥳 We’ve made a number of updates to update all our dependencies to the latest version and introduced new directives you can use to write great docs. You can read more about all notable changes [here](https://sphinx-theme.scylladb.com/master/upgrade/CHANGELOG.html#february-2022). Before, the theme installed [poetry 1.1.x](https://python-poetry.org/) as a dependency to manage Python dependencies. However, ``poetry 1.2.x`` changed the installation method. Therefore, we've decided to [#307 Make poetry a prerequisite](scylladb/sphinx-scylladb-theme#307) so that you can decide to install the poetry version you prefer. To preview the docs locally, you should uninstall the previous version of poetry. Then, install the latest version: 1. Uninstall Poetry 1.1.x. ``` curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | POETRY_UNINSTALL=1 python - ``` 2. Install Poetry 1.2.x. For detailed instructions, see [Poetry installation](https://python-poetry.org/docs/master/#installation). 1. Clone this PR. For more information, see [Cloning pull requests locally](https://docs.github.com/en/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally). 2. Uninstall poetry 1.1 and install poetry 1.2. For more information, see **Breaking changes** notice above. 3. Enter the docs folder, and run: ``` make preview ```` 4. Open http://127.0.0.1:5500/ with your favorite browser. The doc should render without errors, and the version should be Sphinx Theme version (see the footer) must be ``1.1.x``:  Closes #10054 * github.com:scylladb/scylla: Add missing lexer docs: update theme 1.1
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Motivation
If the user does not have it installed poetry, the toolchain installs the package manager automatically using the script located in
docs/_utils/setup.sh.It's a better practice to let the user install Poetry as a prerequisite in their machine for the following reasons:
The user can decide which version of poetry they want to install. We are now forcing them to choose one version, which is usually not the latest.
With the latest version, the installation instructions have changed. Therefore, we should update the script in every repo.
We would get rid of the
docs/_utils/setup.shscript, which is sometimes different between projects depending on when they installed the toolchain.docs/_utils/setup.shmakes the documentation toolchain only compatible with UNIX systems. However, this is not compatible with other OS such as Windows.Proposal
docs/_utils/setup.sh.Before we release the change
When we open issues for each repository to migrate to 1.1, we will link to a guide where we list:
The text was updated successfully, but these errors were encountered: