Update and simplify README installation instructions

[zkamvar]

At the moment, the readme is not quite accurate:

• We do not use a Jupyter book theme, we use the sphinx book theme
• Installation individual packages to the global python environment is frowned upon in the Python world (so I understand). We should provide instructions to set up a virtual environment
• Since it ensh*ttified, we should no longer recommend conda for setting up python. We should probably just move to recommending uv (but maybe this is to @bsweger's chagrin).

[bsweger]

Nah, we had talked a while back (on a dev call, I think) about using uv for the hubDocs project.

I completely agree that it is appropriate to yeet conda into the sun.

[micokoch]

I don't know exactly how the installation instructions have changed, but to build it locally, in addition to the steps listed in the README, I had to do the following:
pip install sphinx_design
pip install sphinxcontrib.mermaid
That should also be mentioned (unless there is a different step).

[zkamvar]

Ideally, you shouldn't have to pip install every single package. The way to do it IIRC is (@bsweger please correct me if I am mistaken)

python -m venv .venv # set up a virtual environment
source .venv/bin/activate # activate it in your local session
pip install -r docs/requirements.txt # install the requirements into the virtual environment

Then every time you come back to the project, you can run source .venv/bin/activate when you want to work on it.

[micokoch]

Thanks @zkamvar ! That is all very helpful. I have a couple of comments:

1. The first instructions in the README should include the most straightforward installation. That is what I usually use, following the ## Installation and building steps. In these, there is no requirement for a virtual environment. Also, now there is a need to install sphinx_design and sphinxcontrib.mermaid separately if one only follows those steps.
2. Those first steps should include the pip install -r docs/requirements.txt even if you don't use a virtual environment.
3. I should note that I encountered error messages when running pip install -r docs/requirements.txt without a virtual environment (a problem with myst-parser==4.0.0) and with the virtual environment (a problem with numpy==1.21.2). Neither of these problems seemed important, as the site was built anyway, but I mention them in case they are important.
4. One matter that caused me tremendous headaches when I just started using Python, so it probably should be clarified from the start, is that you may need to write python or python3 in the commands you mention. Without the virtual environment, I had to write python3, which was needed to create the virtual environment. In the virtual environment, I only needed to write python. This is in spite of the fact that both use the same version of Python.
5. I would usually volunteer to edit the README, but I don't understand all of this enough to write good instructions.

Thanks for looking into this.

[zkamvar]

5. I would usually volunteer to edit the README, but I don't understand all of this enough to write good instructions.

Completely understandable! A lot of this is the reason why https://xkcd.com/1987/ exists.

[annakrystalli]

While I'm fully for simplifying to a single instruction and moving to uv, we do provide instructions to set up a virtual environment: https://github.com/hubverse-org/hubDocs?tab=readme-ov-file#create-environment-and-install-dependencies

[zkamvar]

While I'm fully for simplifying to a single instruction and moving to uv, we do provide instructions to set up a virtual environment: https://github.com/hubverse-org/hubDocs?tab=readme-ov-file#create-environment-and-install-dependencies

Ah yes, but see my previous comment about conda:

Since it ensh*ttified, we should no longer recommend conda for setting up python.