[GitHub] [guacamole-manual] mike-jumper commented on a change in pull request #165: GUACAMOLE-1347: Migrate from DocBook to Sphinx.

[GitBox <gi...@apache.org>]

mike-jumper commented on a change in pull request #165:
URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r646187255



##########
File path: README.md
##########
@@ -0,0 +1,113 @@
+About this README
+=================
+
+This README is intended to document the build process of the Apache Guacamole
+manual for technical users who wish to contribute or who simply wish to build
+the manual themselves.
+
+The [latest version of the manual](http://guacamole.apache.org/doc/gug/) is
+provided on the [Guacamole web site](http://guacamole.apache.org/), and
+snapshot copies of each release are included in the [release
+archives](http://guacamole.apache.org/releases/).
+
+
+What is guacamole-manual?
+=========================
+
+The guacamole-manual package is the base documentation for the entire Guacamole
+stack. It is largely written in [the "MyST" flavor of Markdown](https://myst-parser.readthedocs.io/en/latest/index.html),
+with portions of the documentation written in reStructuredText where necessary
+(the Guacamole protocol reference).
+
+MyST was chosen as the primary format because:
+
+ * As a variant of Markdown, it will be widely approachable and familiar.
+ * It is supported by Sphinx.
+ * It provides additional syntax for the features of reStructuredText that are
+   absent from standard Markdown (like admonitions).
+ * It provides the features of Markdown that are absent from reStructuredText
+   (like nested inline formatting, including formatting within links or links
+   within formatted text).
+
+reStructuredText is occasionally necessary because:
+
+ * [MyST does not support docstring field lists](https://github.com/executablebooks/MyST-Parser/issues/163#issuecomment-640008632),
+   a feature of reStructuredText required for documenting APIs. We use this
+   feature for documenting the Guacamole protocol.
+ * The MyST solution to supporting docstrings is [embedding blocks of
+   reStructuredText](https://myst-parser.readthedocs.io/en/latest/using/howto.html#use-sphinx-ext-autodoc-in-markdown-files).
+
+The build process involves running the Guacamole manual source through the
+tooling provided by the Sphinx project, in particular "sphinx-build".
+
+
+Building the manual
+===================
+
+1. Ensure [Sphinx](https://pypi.org/project/Sphinx/), the [Sphinx ReadTheDocs
+   theme](https://pypi.org/project/sphinx-rtd-theme/),
+   [sphinx-inline-tabs](https://pypi.org/project/sphinx-inline-tabs/), and the
+   [MyST parser](https://pypi.org/project/myst-parser/) are installed. These can
+   be installed using "pip":
+
+   ```console
+   $ pip install sphinx sphinx-rtd-theme sphinx-inline-tabs myst-parser
+   ```
+
+2. Run make:
+
+   ```console
+   $ make
+   ```

Review comment:
       OK - I've added more a specific build requirements list that includes Python 3.8 and notes that "pip" might be called "pip3".




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org