Update website documentation (#2914)

Summary:
Pull Request resolved: #2914

X-link: facebook/Ax#4001

1. Fix instructions for building sphinx locally. The makefile was using an old destination from before we migrated to ReadTheDocs. This didn't affect ReadTheDocs or our own workflow tests (neither use the makefile) but correct documentation allows us to debug sphinx locally more easily.
2. Remove old and incorrect Ax website documentation in `CONTRIBUTING.md`. Remove this old documentation and instead point users to the docs in `website/README.md`
3. Add `website/README.md` to the botorch repo. This was mistakenly missing. Remove old botorch documentation from `CONTRIBUTING.md` and point to `website/README.md` same as the Ax repo.

Reviewed By: Balandat

Differential Revision: D77888215

fbshipit-source-id: 95aca46f5f3b74ba176c67b8e5ae92dd70e8df91

Author: CristianLara

CONTRIBUTING.md

@@ -96,7 +96,7 @@ code can be found in the [website](/website/) folder). It is built using
    [Sphinx](http://www.sphinx-doc.org), and embedded into the Docusaurus
    website. The sphinx .rst source files for this live in
    [sphinx/source](/sphinx/source/).
-3. The Jupyter notebook tutorials, parsed by `nbconvert`, and embedded into the
+3. The Jupyter notebook tutorials, parsed and converted to MDX, and embedded into the
    Docusaurus website. These live in [tutorials](/tutorials/).
 
 To build the documentation you will need [Node](https://nodejs.org/en/) >= 8.x
@@ -108,6 +108,8 @@ The following command will both build the docs and serve the site locally:
 ./scripts/build_docs.sh
 ```
 
+See the [website/README.md](website/README.md) for more details.
+
 ## Pull Requests
 
 We actively welcome your pull requests.

website/README.md

@@ -0,0 +1,74 @@
+The Botorch website was created with [Docusaurus](https://docusaurus.io/), with some customization to support tutorials, and supplemented with Sphinx for API documentation.
+
+## Dependencies
+
+Ensure necessary dependencies are installed (ideally to your virtual env):
+```bash
+pip install -e ".[tutorials]"
+```
+
+## Building (all-in-one)
+
+For convenience we provide a single shell script to convert the tutorials and build the website in one command. Must be executed from the repository root.
+```bash
+./scripts/build_docs.sh
+```
+
+To also execute the tutorials, add the `-t` flag.
+To generate a static build add the `-b` flag.
+
+`-h` for all options.
+
+
+## Building (manually)
+
+### Notebooks
+
+Tutorials can be executed locally using the following script. This is optional for locally building the website and is slow.
+```bash
+python3 scripts/run_tutorials.py -w .
+```
+
+We convert tutorial notebooks to MDX for embedding as docs. This needs to be done before serving the website and can be done by running this script from the project root:
+
+```bash
+python3 scripts/convert_ipynb_to_mdx.py --clean
+```
+
+### Docusaurus
+You need [Node](https://nodejs.org/en/) >= 18.x and
+[Yarn](https://yarnpkg.com/en/) in order to build the Botorch website.
+
+Switch to the `website` dir from the project root and start the server:
+```bash
+cd website
+yarn install
+yarn start
+```
+
+Open http://localhost:3000 (if doesn't automatically open).
+
+Anytime you change the contents of the page, the page should auto-update.
+
+> [!NOTE]
+> You may need to switch to the "Next" version of the website documentation to see your latest changes.
+
+### Sphinx
+Sphinx is used to generate an API reference from the source file docstrings. In production we use [ReadTheDocs](https://botorch.readthedocs.io/en/stable/index.html) to build and host these docs, but they can also be built locally for testing.
+```sh
+cd sphinx/
+make html
+```
+
+The build output is in `sphinx/build/html/` but Sphinx does not provide a server. Here's a serving example using Python:
+
+```sh
+cd sphinx/build/html/
+python3 -m http.server 8000
+```
+
+
+## Publishing
+
+The site is hosted on GitHub pages, automatically deployed using the Github [deploy-pages](https://github.com/actions/deploy-pages) action - see the
+[config file](https://github.com/pytorch/botorch/blob/main/.github/workflows/publish_website.yml) for details.