Update README and include in index.rst

Author: benjaoming

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# auto-generated Sphinx api docs
+/docs/generated
+
 # Distribution / packaging
 .Python
 build/

README.rst

@@ -1,2 +1,64 @@
-# example-sphinx-basic
-A basic Sphinx project
+Example: Basic Sphinx project for Read the Docs
+===============================================
+
+This example shows the following basic integration with Read the Docs:
+
+* A basic Sphinx project lives in ``docs/`` 📚
+* Read the Docs Build configuration is stored in ``.readthedocs.yaml`` ⚙️
+* Python dependencies are `pinned <https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html>`_ 📍
+* Auto-generated API docs for a Python module called ``lumache`` 💡
+* Sphinx documentation integrates Python docstrings directly from ``lumache`` 💡
+* A basic versioning mechanism with git tags 🔢
+* Contents of this ``README.rst`` are visible on Github and included on `the documentation index page <https://example-sphinx-basic.readthedocs.io/en/latest/>`_ (Don't Repeat Yourself) 📜
+* If you have questions related to this example, feel free to can ask them as a Github issue `here <https://github.com/readthedocs-examples/example-sphinx-basic/issues>`_. ⁉️
+
+
+Sphinx Example Project usage
+----------------------------
+
+This project has a very normal Sphinx layout which is built by the Read the Docs platform almost the same way that you would build it locally (on your own laptop!).
+
+You can build and view this documentation project locally - you may want to activate `a local Python virtual environment firstly <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`_:
+
+.. code-block:: console
+
+    # Install required Python dependencies (Sphinx etc.)
+    pip install -r docs/requirements.txt
+
+    # Enter the Sphinx project
+    cd docs/
+    make html
+
+
+You can also build the documentation locally with ``make``:
+
+.. code-block:: console
+
+    # Enter the Sphinx project
+    cd docs/
+    
+    # Build with make
+    make html
+    
+    # Open with your preferred browser
+    firefox _build/html/index.html
+
+
+Using the example in your own project
+-------------------------------------
+
+If you are new to Read the Docs, you may want to refer to the `Read the Docs User documentation <https://docs.readthedocs.io/>`_.
+
+If you are copying this code in order to get started with your documentation, you need to:
+
+* Create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs
+* Customize all ``docs/*.rst`` files
+* Add your own Python project, replacing the ``pyproject.toml`` configuration and ``lumache.py`` module.
+* Rebuild the documenation locally to see that it works.
+* Register your project on Read the Docs, see `Importing Your Documentation <https://docs.readthedocs.io/en/stable/intro/import-guide.html>`_.
+
+
+Read the Docs tutorial
+----------------------
+
+To get started with Read the Docs, you may also refer to the `Read the Docs tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`_

docs/index.rst

@@ -1,3 +1,5 @@
+.. include:: ../README.rst
+
 Welcome to Lumache's documentation!
 ===================================