Renovate docs/README (#5255)

- change it to markdown and add `.md` in the name
- update the windows guide, no need to use a different command
- move unclear notes into a hidden toggle (I am not even sure if we need this info)
- update the requirements, add an installation instruction
- general cleanup

2 files changed, 34 insertions, 23 deletions

diff --git a/docs/README b/docs/README
deleted file mode 100644
index db5a80c91..000000000
--- a/docs/README
+++ /dev/null
@@ -1,23 +0,0 @@
-Welcome to Cython's documentation.
-
-To build the documentation on Linux, you need Make and Sphinx installed on your system. Then execute::
-
-	make html
-
-On windows systems, you only need Sphinx. Open PowerShell and type::
-
-	./make.bat html
-
-You can then see the documentation by opening in a browser ``cython/docs/build/html/index.html``.
-
-The current Cython documentation files are hosted at
-https://cython.readthedocs.io/
-
-
-Notes
-=======
-
-1) Some css work should definitely be done.
-2) Use local 'top-of-page' contents rather than the sidebar, imo.
-3) Provide a link from each (sub)section to the TOC of the page.
-4) Fix cython highlighter for cdef blocks
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..b18c53a3b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,34 @@
+# Welcome to Cython's documentation
+
+The current Cython documentation is hosted at [cython.readthedocs.io](https://cython.readthedocs.io/)
+
+The main documentation files are located in the `cython/docs/src` folder and the code that is used in those documents is located in the `cython/docs/examples`
+
+Before building, you need to install `doc-requirements.txt` (and `make` on Linux).
+
+To install `doc-requirements.txt` run in the root folder
+
+```shell
+pip install -r doc-requirements.txt
+```
+
+To build the documentation go into `docs` folder and run
+
+```shell
+make html
+```
+
+You can then see the documentation by opening `cython/docs/build/html/index.html` in a browser.
+
+Generally follow the structure of the existing documents.
+
+If you are creating a (sub)section add a link for it in the TOC of the page.
+
+<details>
+<summary>Notes</summary>
+
+1) Some css work should definitely be done.
+2) Use local 'top-of-page' contents rather than the sidebar, imo.
+3) Fix cython highlighter for cdef blocks
+
+</details>