doc: update Python req. for sphinx (#1733)

* doc: update Python req. for sphinx

* Upgrade the sphinx/requirements.txt to use latest versions of the
  following modules:
  * requests==2.24.0
  * sphinx==3.2.1
  * sphinx-markdown==1.0.2
  * recommonmark==0.6.0
  * breathe==4.23.0
* Update the sphinx configuration to use recommonmark instead
  of pandoc_markdown.
* Tweak some of the .rst files according to some warnings emitted by
  sphinx.
  * TODO: Fix other warnings in another pull request.
* Tweak build-documentation.sh script to simply build the documentation
  but not upload it to github.io
* doc: update doc build flow
* Add documentation build job to github actions
* Update travis apt requirements
* Add cmake messages to help diagnosing when building documentation
  fails
* clean up build-documentation.sh script
  * remove dead code
  * terminate if installing python requirements fails
* clean up push-documentation.sh script
  * set user to "OPAE Bot", opae_robot@intel
* doc: update gh action for Python setup
* doc: cleanup gh action, build-documentation script

* remove the gh setup python action and rely on the distro version of
python
* because build-documentation.sh is installing python packages with
--user, add ~/.local/bin to PATH

* doc: add python setuptools pkg to gh actions job

* doc: fix some warning in sphinx build

* doc: add doc artifacts to github action

* docs: add link checker in ci

* doc: upload link-checker results.


* docs: use docker img for building docs

* Add Dockerfile that builds an image with required packages for
  building documentation
  * This file was used to create and upload a docker image
    opae/docs-builder
* Change CI to pull docker image and build the documentation with it

* docs: fix docker img name

* Update no-python-analysis.yml

.build.json

@@ -31,5 +31,12 @@
             "OPAE_BUILD_TESTS": "ON",
             "OPAE_ENABLE_MOCK": "ON"
         }
+    },
+    "docs":
+    {
+	"defs":
+	{
+	    "OPAE_BUILD_SPHINX_DOC": "ON"
+	}
     }
 }

.github/workflows/ccpp-tests.yml

@@ -82,3 +82,36 @@ jobs:
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
         path-to-lcov: unittests/coverage.info.cleaned
+  build-doc:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: update
+      run: sudo apt-get update -y
+    - name: Pull opae/docs-builder docker image
+      run: docker pull opae/docs-builder
+    - name: Build Documentation
+      run: docker run --rm -v ${{ github.workspace }}:/root opae/docs-builder ./scripts/build-documentation.sh
+    - name: Upload latest to github.io
+      if: ${{ github.ref == 'refs/heads/master' }}
+      working-directory: ${{ github.workspace }}/mybuild_docs
+      run: ${{ github.workspace }}/scripts/push-documentation.sh latest
+    - name: Upload tag to github.io
+      if: startsWith(github.ref, 'refs/tags/')
+      working-directory: ${{ github.workspace }}/mybuild_docs
+      run: ${{ github.workspace }}/scripts/push-documentation.sh "${GITHUB_TAG##*/}"
+    - name: Archive html docs
+      uses: actions/upload-artifact@v1
+      with:
+        name: docs
+        path: mybuild_docs/sphinx/html
+    - name: Link Checker
+      uses: peter-evans/link-checker@v1
+      with:
+        args: -v -r mybuild_docs/sphinx/html
+    - name: Archive link-checker result
+      uses: actions/upload-artifact@v1
+      with:
+        name: link-checker
+        path: link-checker
+

.github/workflows/no-python-analysis.yml

@@ -1,4 +1,4 @@
-name: python static analysis
+name: python static analysis (dummy)
 
 on:
   workflow_dispatch:

.travis.yml

@@ -57,14 +57,13 @@ matrix:
         - libtbb-dev
         - uuid-dev
         - doxygen
-        - pandoc
+        - python3-dev
+        - python3-sphinx
+        - python3-pip
     if: branch = master
     install:
       - pip install --user jinja2
       - pip install --user requests[security]
-    before_install:
-    - wget https://github.com/jgm/pandoc/releases/download/2.1.1/pandoc-2.1.1-1-amd64.deb
-    - sudo dpkg -i pandoc-2.1.1-1-amd64.deb
 env:
   global:
     secure: ejmtge9PpCihZ92AolJhTBWGTYUU49dzwR10xBd62JfDSXWs8UYu3FSGodLQcMm4XdaM0uDthJ1MzvP/CphgMCOIyzVr6XLF8JFLVLw6cP1P0Q5Kgj1qN9f8DZL3VrgyRSL7lRuxQt4qP8eXLlksEAi+PKrka2hsNnUtoX8JBYHeeos7b+Q4vq4d/PzpIrhrYIQy1RlatAAhGG8JsD3R2WdkNwK3kGUvcAwZirROfRAf+xaPRKCTHtRfNehTCu93v9n1uYdxDAWw7RJOjjYp+HUGj7XUTi28D7kcz5zOKp6Ny7Cgf3SgQqwK4xF+Jidk/g5i9V8D0Qi0oplbD6vekp0zVU6k8IWLZgtfqw9CnRV2Tv7e7a7oMUsFoKEW3pT/U1lU1fKuEddTUlf8myMoAm6VcEXXtboz2xP9svpNvDjnATU8CTtN1eEdrOpmI6FjYZv133twkfP61bEKgv05w8416/jvcil3CXnzVGFkbO2oXCr1uWe3t/JjEon8W+rgnxl9uC/QeEd1uFwOi3/UBB+ZQp8khbMz68iRSux7g+mGiZ6Ezbr0WaSIz6ZiliFykLCbpyAJduHIUCc1chF20Xq8105D/Ue4nCOnI/h/vC/BsQ5Ms+VAYk1QHPgNXKEc2pteVxHaTg7c6qoHsBV+NTkdd4QJvNuS+jzZsxao7JQ=

CMakeLists.txt

@@ -77,9 +77,11 @@ endif()
 option(OPAE_BUILD_SPHINX_DOC "Enable building of Sphinx documentation." OFF)
 mark_as_advanced(OPAE_BUILD_SPHINX_DOC)
 
-if (DOXYGEN_FOUND)
+if(DOXYGEN_FOUND)
     add_subdirectory(doc)
-endif()
+else(DOXYGEN_FOUND)
+    message(STATUS "Documentation cannot be built without doxygen")
+endif(DOXYGEN_FOUND)
 
 ############################################################################
 ## Packaging ###############################################################

doc/CMakeLists.txt

@@ -29,7 +29,11 @@ if(DOXYGEN_FOUND)
   add_subdirectory(doxygen)
 endif(DOXYGEN_FOUND)
 
-find_package(Sphinx)
-if(OPAE_BUILD_SPHINX_DOC AND SPHINX_EXECUTABLE)
-  add_subdirectory(sphinx)
-endif(OPAE_BUILD_SPHINX_DOC AND SPHINX_EXECUTABLE)
+if(OPAE_BUILD_SPHINX_DOC)
+    find_package(Sphinx)
+    if(SPHINX_EXECUTABLE)
+        add_subdirectory(sphinx)
+    else(SPHINX_EXECUTABLE)
+        message(FATAL "Sphinx not found")
+    endif(SPHINX_EXECUTABLE)
+endif(OPAE_BUILD_SPHINX_DOC)

doc/sphinx/CMakeLists.txt

@@ -71,7 +71,9 @@ add_custom_target(copy-sample-files ALL
   DEPENDS copy-include-files)
 
 add_custom_target(copy-python-files ALL
-  COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/opae-libs/pyopae/README.md ${BINARY_BUILD_DIR}/docs/README.md
+  COMMAND ${CMAKE_COMMAND} -E copy
+  ${CMAKE_SOURCE_DIR}/opae-libs/pyopae/README.md
+  ${BINARY_BUILD_DIR}/docs/pyopae/README.md
   DEPENDS copy-markdown-files)
 
 

doc/sphinx/conf.py.in

@@ -8,9 +8,8 @@ import shutil
 # Better fonts
 import sphinx_fontawesome
 
-# Pandoc-based markdown parser for sphinx
-from sphinxcontrib.pandoc_markdown import MarkdownParser
-
+from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
 # Enabled extensions
 extensions = [
     'sphinx.ext.autodoc',
@@ -22,6 +21,7 @@ extensions = [
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx_fontawesome',
+    'recommonmark',
     'breathe'
 ]
 
@@ -35,7 +35,7 @@ breathe_projects = {'FPGA-API' : 'doxygen_xml/'}
 breathe_default_project = 'FPGA-API'
 
 # Do not use this; if _contrib markdown plugin was used
-source_parsers = { '.md': MarkdownParser}
+source_parsers = { '.md': CommonMarkParser}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -199,7 +199,7 @@ def setup(app):
         # 'url_resolver': lambda url: github_doc_root + url,
         'auto_toc_tree_section': 'Contents',
         'enable_eval_rst': True,
-        'enable_auto_doc_ref': True,
         'enable_math': True,
         'enable_inline_math': True,
         }, True)
+    app.add_transform(AutoStructify)

doc/sphinx/index.rst.in

@@ -19,7 +19,7 @@ The main documentation for the site is organized into following sections:
    docs/install_guide/installation_guide
    docs/fpga_api/prog_guide/readme
    docs/ase_userguide/ase_userguide
-   docs/README
+   docs/pyopae/README
 
 .. _api-docs:
 

doc/sphinx/requirements.txt

@@ -1,9 +1,9 @@
-requests==2.20.0
+requests==2.24.0
 docutils==0.14
 pygments==2.2.0
-sphinx==1.6.5
+sphinx==3.2.1
 sphinx-rtd-theme==0.4.3
 sphinx_fontawesome==0.0.6
-sphinxcontrib-pandoc-markdown==1.6.8
-breathe==4.0.0
-travis-sphinx
+sphinx-markdown==1.0.2
+recommonmark==0.6.0
+breathe==4.23.0

doc/src/ase_userguide/ase_userguide.md

@@ -189,7 +189,7 @@ Download the ASE as source or in RPM format.
 
 The source directory tree is:
 
-```{.shell}
+```shell
 
     OPAE_BASEDIR
         |-- ase
@@ -255,7 +255,7 @@ or the RTL simulator user guides for help setting up the tools.
 This script checks the status of the OS distribution, distro, and available system libraries. This check is a non-exhaustive.
 It looks for only the most important dependencies, such as the GCC version, GLIBC version, and so on.
 
-```{.bash}
+```bash
 
     $ ./ase/scripts/env_check.sh
 
@@ -277,7 +277,7 @@ Refer to the [ASE Example](#ase-example) section below for a sample workload def
 The ```afu_sim_setup``` script reads a file containing a list of RTL sources (\<rtl_sources.txt\>) and configures a simulation
 environment for the specified sources. The ```afu_sim_setup``` command copies your base ASE environment to the \<target dir\>.
 
-```{.bash}
+```bash
 
     $ afu_sim_setup --sources=<rtl_sources.txt> <target dir>
 
@@ -350,7 +350,7 @@ variables in the generated files that build and run the simulator.
 Use the ASE cleanup script located in ```scripts/ipc_clean.py``` to kill zombie simulation processes and temporary files left
 behind by failed simulation processes or crashes.
 
-```{.bash}
+```bash
 
     $ ./ase/scripts/ipc_clean.py
 
@@ -425,7 +425,7 @@ Follow these instructions if you are building the OPAE SDK from a source tar fil
 
 * To build the OPAE libraries:
 
-```{.bash}
+```bash
 
     # Change directory to the opae directory
     $ cd /tmp/opae/
@@ -475,7 +475,7 @@ You can build the software application using one of the following three methods:
 
 ##### Dynamically Linking libopae-c-ase.so #####
 
-```{.bash}
+```bash
 
     # Change directory to <Path to Directory>/opae/samples/
     #   The UUID code requires the -luuid argument
@@ -493,7 +493,7 @@ The ASE implementation of the OPAE library simulates system behavior. Consequent
 to the System library, `libopae-c.so` and `libopae-c-ase.so`, and then override the system library with the
 ```LD_PRELOAD``` environment.
 
-```{.bash}
+```bash
 
     # Change directory to <Path to Directory>/opae/samples/
     #   The UUID code requires the -luuid argument
@@ -511,7 +511,7 @@ to the System library, `libopae-c.so` and `libopae-c-ase.so`, and then override
 
 Use the OPAE ASE library implementation and compile it to the OPAE software application directly in one command using GCC.
 
-```{.bash}
+```bash
 
     # Compile command
     $ gcc -g -o hello_fpga_ase hello_fpga.c /tmp/opae/myinst/lib/libopae-c-ase.so -I /tmp/opae/myinst/include/ -std=c99 -luuid
@@ -548,7 +548,7 @@ requires manual inspection of generated configurations to achieve correct result
 
 You may use the [Generate ASE Environment](#generate_ase_environment.py) script to generate the required AFU ```ase_sources.mk``` and ```vlog_files.list``` files.
 
-```{.bash}
+```bash
 
     # change to ASE directory
     $ cd /tmp/opae/ase/
@@ -583,7 +583,7 @@ with a 'make' command.
 
 The ASE server-client simulator makes the server before the client. Here are the run-time options:
 
-```{.bash}
+```bash
 
     $ make sim \
         [SIMULATOR=<VCS|QUESTA>] \
@@ -652,7 +652,7 @@ You can close Terminal 1 ```make sim```by issuing a ```SIGTERM``` to the relevan
 * Terminal: First set the environment variable ```ASE_WORKDIR``` as specified in Terminal 1. In this example ```ASE_WORKDIR```
 is set to ```/tmp/opae/ase/work```.  Then, start the software application.
 
-```{.bash}
+```bash
 
     # Set ASE_WORKDIR environment variable
     $ export ASE_WORKDIR=/tmp/opae/ase/work/
@@ -671,7 +671,7 @@ is set to ```/tmp/opae/ase/work```.  Then, start the software application.
 ```
 
 
-```{.bash}
+```bash
 
 
 
@@ -758,7 +758,7 @@ while simulating, consider using the handle ```start_simkill_countdown()``` inst
 3. You can script ASE simulations. When the simulator is ready for use, the simulation writes a lock file,
 ```$ASE_WORKDIR/.ase_ready```, to the work directory.
 
-```{.bash}
+```bash
 
     # Start Simulator in background
     make sim &
@@ -982,7 +982,7 @@ variable ```ASE_LOG``` to ```0```.
 
 The following command  suppresses the ASE_MSG category:
 
-````{.bash}
+````bash
 
     $ ASE_LOG=0 LD_PRELOAD=libopae-c-ase ./hello_fpga
 

doc/src/drv_arch/drv_arch.md

@@ -1,12 +1,11 @@
 # Open Programmable Accelerator Engine (OPAE) Linux Device Driver Architecture #
 
+```eval_rst
 .. toctree::
-
 .. highlight:: c
-
 .. highlight:: sh
-
 .. highlight:: console
+```
 
 The OPAE FPGA Linux Device Driver provides interfaces for user-space applications to
 configure, enumerate, open, and access FPGA accelerators on platforms equipped

doc/src/fpga_api/fpga_api.rst

@@ -120,15 +120,15 @@ manage.h
 
 .. doxygenfile:: include/opae/manage.h
 
-Metrics API
-==============
-
+Metrics API
+==============
+
 The metrics APIs define functions for discovery/enumeration of metrics information
-and reading metrics values.
-
-metrics.h
---------
-
+and reading metrics values.
+
+metrics.h
+---------
+
 .. doxygenfile:: include/opae/metrics.h
 
 SysObject
@@ -142,7 +142,7 @@ tree for the resource used with the SysObject API.
 
 
 sysobject.h
--------
+-----------
 
 .. doxygenfile:: include/opae/sysobject.h
 

doc/src/fpga_api/fpga_cxx_api.rst

@@ -135,12 +135,12 @@ handle.h
 .. doxygenfile:: include/opae/cxx/core/handle.h
 
 shared_buffer.h
---------
+---------------
 
 .. doxygenfile:: include/opae/cxx/core/shared_buffer.h
 
 errors.h
--------
+--------
 
 .. doxygenfile:: include/opae/cxx/core/errors.h
 
@@ -150,7 +150,7 @@ events.h
 .. doxygenfile:: include/opae/cxx/core/events.h
 
 sysobject.h
--------
+-----------
 
 .. doxygenfile:: include/opae/cxx/core/sysobject.h
 
@@ -175,7 +175,7 @@ Misc
 The `version` class wraps the OPAE C version API.
 
 version.h
---------
+---------
 
 .. doxygenfile:: include/opae/cxx/core/version.h
 

doc/src/fpga_api/fpga_python_api.rst

@@ -45,7 +45,7 @@ Event
 Shared Buffer
 -------------
 .. autoclass:: opae.fpga.shared_buffer
-        :members: size, wsid, iova, fill, compare, memoryview
+        :members: size, wsid, io_address, fill, compare
 
 Error
 -----