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

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

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



##########
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
+   ```

Review comment:
       Not sure how much to make of this, but in my install of RHEL7, Sphinx would not install using the default `pip` command, which uses python2, and I had to use the `pip3` command, instead.

##########
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:
       ....aaaand, looks like another error, here:
   ```
   [root@ussalxapps005t guacamole-manual]# make
   sphinx-build -b html -d build/doctrees src/ build/html
   Running Sphinx v4.0.2
   
   Exception occurred:
     File "/usr/local/lib/python3.6/site-packages/sphinx_inline_tabs/_impl.py", line 4, in <module>
       from typing import List, Literal
   ImportError: cannot import name 'Literal'
   The full traceback has been saved in /tmp/sphinx-err-09sl6lmj.log, if you want to report the issue to the developers.
   Please also report this if it was a user error, so that a better error message can be provided next time.
   A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
   make: *** [build/html/index.html] Error 2
   ```
   According to the interwebs, `Literal` is possibly only available in Python 3.8, and EL7 ships with Python 3.6. On CentOS it can be installed with the CentOS SCLO RH repos, but definitely won't work out-of-the-box.
   
   On my CentOS test system I was able to run build successfully using the following steps:
   ```
   $ sudo yum install rh-python38-python-pip
   $ . /opt/rh/rh-python38/enable
   $ pip3.8 install sphinx sphinx-rtd-theme sphinx-inline-tabs myst-parser
   $ make
   ```
   Not sure how much of this detail is worth placing in here versus just noting that Python3.8 is required.




-- 
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