chore: update README in the docs directory (#276)

Signed-off-by: Trong Nhan Mai <[email protected]>

Author: Trong Nhan Mai

docs/README.md

@@ -1,40 +1,28 @@
 # Macaron documentation
-This directory contains the Sphinx documentation for Macaron.
+This directory contains the source for the documentation of Macaron hosted [here](https://oracle-samples.github.io/macaron/).
 
-## Generating the HTML documentation from source
-**Note**: We only include the API documentation at the moment. Other sections in the documentation will be migrated in the future.
-
-First, make sure you have all the dependencies required to build the documentation (Assume we run the following commands in the root directory of this repo).
-
-**TODO**: Add docs dependencies to `pyproject.toml`.
-
-```
-python -m pip install --editable .
-```
-
-To generate documentation in html form:
+## Build the documentation
 
+To build the documentation, please follow these steps:
+1. Setup the dev environment for Macaron using the instructions [here](../README.md#getting-started).
+2. Build the documentation by running this command from the root directory of Macaron:
 ```
-sphinx-build -b html docs/source docs/build -E
+make docs
 ```
 
-Or within the [docs](./) folder, run:
-```
-make html
-```
-
-To view the html documentation on localhost:
+This command will build and generate the documentation into `docs/_build/html`. To view it locally, run (with the dev environment activated):
 
 ```
 python3 -m http.server -d docs/_build/html
 ```
 
-## For developers: Generating the API docs.
-The Sphinx API docs for Macaron can be generated using the [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) tool that comes with `sphinx`.
+## Extend the API reference.
+
+If you add a new module, make sure that it is added to the API reference. The API reference is generated using the [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) tool.
 
-From within the root directory of Macaron, run:
+From within the root directory of Macaron, run (with the dev environment activated):
 ```
 sphinx-apidoc --no-toc --module-first --force --maxdepth 1 --output-dir docs/source/pages/apidoc/ src/
 ```
 
-The output RST files will be generated into [pages/apidoc/](./source/pages/apidoc/) where it will be picked up when we build the documentation.
+This command will  generate the API reference RST files into `docs/source/pages/apidoc/`. Make sure to check in the changed source files to the repository.