utf-8 encoding for doc/usersguide (#10570)

- Fixes for building User's Guide in devcontainer using build-deps:v1.16.4
- Updating Readme of User's Guide on how to build it.

Author: AnHeuermann

doc/README.md

@@ -3,4 +3,4 @@
 There are different documentations available for OpenModelica.
 
   - The User's Guide, see [UsersGuide/README.md](https://github.com/OpenModelica/OpenModelica/blob/master/doc/UsersGuide/README.md)
-  - Doxygen documentation for parts of the C, C++ and OMSI documentation
+  - Doxygen documentation for parts of the C, C++ and OMSI documentation

doc/UsersGuide/.gitignore

@@ -1,68 +1,2 @@
 /build
-source/*.pyc
-source/logo.pdf
 /tmp
-source/LotkaVolterra*.*
-source/dcmotor.*
-source/ProfilingTest_prof*
-source/VanDerPol.pdf
-source/VanDerPol.png
-source/VanDerPol.svg
-source/bouncingball_fmu.pdf
-source/bouncingball_fmu.png
-source/bouncingball_fmu.svg
-source/externallibraries.pdf
-source/externallibraries.png
-source/externallibraries.svg
-source/helloworld-detailed.pdf
-source/helloworld-detailed.png
-source/helloworld-detailed.svg
-source/helloworld-euler.pdf
-source/helloworld-euler.png
-source/helloworld-euler.svg
-source/helloworld.pdf
-source/helloworld.png
-source/helloworld.svg
-source/nmpc-input.pdf
-source/nmpc-input.png
-source/nmpc-input.svg
-source/nmpc-states.pdf
-source/nmpc-states.png
-source/nmpc-states.svg
-source/openmodelica.bib
-source/switch.pdf
-source/switch.png
-source/switch.svg
-source/interface.inc
-source/tmp.rst
-source/tmp.wiki
-source/media/omedit-icons
-source/media/mathematica-notebooks.pdf
-source/media/omoptim-icons/
-source/omchelptext.rst
-source/omreleaselink.inc
-source/simoptions.inc
-source/testmodel.pdf
-source/testmodel.png
-source/testmodel.svg
-source/__pycache__/
-source/media/mdt-build-prompt.pdf
-source/media/mdt-create-project.pdf
-source/media/systemoverview.pdf
-source/omnotebook-closed-loop.pdf
-source/omnotebook-closed-loop.png
-source/omnotebook-closed-loop.svg
-source/omnotebook-drcontrol-imgposroots.pdf
-source/omnotebook-drcontrol-imgposroots.png
-source/omnotebook-drcontrol-imgposroots.svg
-source/omnotebook-drcontrol-negroots.pdf
-source/omnotebook-drcontrol-negroots.png
-source/omnotebook-drcontrol-negroots.svg
-source/omnotebook-open-loop.pdf
-source/omnotebook-open-loop.png
-source/omnotebook-open-loop.svg
-source/testmodel-plotall.pdf
-source/testmodel-plotall.png
-source/testmodel-plotall.svg
-source/omsimulator-help.inc
-

doc/UsersGuide/Makefile

@@ -60,6 +60,7 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	git clean -fX source/
 
 html: all-dep
 	$(SPHINXBUILD) -b html -t nomathjax $(ALLSPHINXOPTS) $(BUILDDIR)/html

doc/UsersGuide/README.md

@@ -1,15 +1,35 @@
-# Users Guide
-OpenModelica users guide using Sphinx (Python Documentation Generator).
+# User's Guide
+
+OpenModelica User's Guide using Sphinx (Python Documentation Generator).
 
 ## Dependencies
+
+Getting all dependencies right is a nightmare. Just use the dev container
+`build-deps:v1.16.4` from [.devcontainer/README.md](./../../.devcontainer/README.md) and
+set `GITHUB_AUTH`.
+
+ - omc, omc-diff and omsimulator
  - Inkscape
  - Sphinx
  - Python3 and packages from [requirements.txt](https://raw.githubusercontent.com/OpenModelica/OpenModelica-doc/master/UsersGuide/source/requirements.txt)
+ - Python PyGithub package
+
+### GITHUB_AUTH
+
+Create a read-only personal access token (API token) on GitHub.com and define an
+environment variable `GITHUB_AUTH` with your secret API token.
+```bash
+export GITHUB_AUTH=XXXXXXXXXXX
+```
+This is needed to read release information from
+https://github.com/OpenModelica/OpenModelica with the PyGithub package.
 
 ### Unix
+
 - Install the Python dependencies using `pip3 install -r source/requirements.txt`
 
 ### Windows MinGW
+
 - Install `Python 2.7`.
 - Install `pip 7.1.2`.
 - Install `bibtexparser` using `pip install bibtexparser`.
@@ -18,9 +38,9 @@ OpenModelica users guide using Sphinx (Python Documentation Generator).
 - Install `sphinxcontrib-bibtex` using `pip install sphinxcontrib-bibtex`.
 - Install `sphinxcontrib-inlinesyntaxhighlight` using `pip install sphinxcontrib-inlinesyntaxhighlight`.
 - Install `ompython`. See [OpenModelica OMPython instructions](https://github.com/OpenModelica/OMPython#installation) on how to install OMPython.
-- Install `pandoc` and make sure its in PATH.
-- Install `gnuplot` and make sure its in PATH.
-- Install `inkscape` and make sure its in PATH.
+- Install `pandoc` and make sure it's in PATH.
+- Install `gnuplot` and make sure it's in PATH.
+- Install `inkscape` and make sure it's in PATH.
 
 ## Build instructions
 ```bash

doc/UsersGuide/source/.gitignore

@@ -1,10 +1,77 @@
+__pycache__/
+*.pyc
+api
+bouncingball_fmu.pdf
+bouncingball_fmu.png
+bouncingball_fmu.svg
+dcmotor.*
+externallibraries.pdf
+externallibraries.png
+externallibraries.svg
+githubreleases.md
+githubreleases.rst
+githubreleases.tmp.rst
+helloworld-detailed.pdf
+helloworld-detailed.png
+helloworld-detailed.svg
+helloworld-euler.pdf
+helloworld-euler.png
+helloworld-euler.svg
+helloworld.pdf
+helloworld.png
+helloworld.svg
+images
+interface.inc
+logo.pdf
+LotkaVolterra*.*
+media/mathematica-notebooks.pdf
+media/mdt-build-prompt.pdf
+media/mdt-create-project.pdf
+media/omedit-icons
+media/omoptim-icons/
+media/systemoverview.pdf
 Modelica.Mechanics.*
+nmpc-input.pdf
+nmpc-input.png
+nmpc-input.svg
+nmpc-states.pdf
+nmpc-states.png
+nmpc-states.svg
+omchelptext.rst
 OMCScripting.inc
+omnotebook-closed-loop.pdf
+omnotebook-closed-loop.png
+omnotebook-closed-loop.svg
+omnotebook-drcontrol-imgposroots.pdf
+omnotebook-drcontrol-imgposroots.png
+omnotebook-drcontrol-imgposroots.svg
+omnotebook-drcontrol-negroots.pdf
+omnotebook-drcontrol-negroots.png
+omnotebook-drcontrol-negroots.svg
+omnotebook-open-loop.pdf
+omnotebook-open-loop.png
+omnotebook-open-loop.svg
+omreleaselink.inc
+omsimulator
+omsimulator-help.inc
 OMSimulatorLib.inc
 OMSimulatorLua.inc
 OMSimulatorPython.inc
-api
-images
-omsimulator
+openmodelica.bib
+ProfilingTest_prof*
 releaselink.inc
-
+simoptions.inc
+switch.pdf
+switch.png
+switch.svg
+testmodel-plotall.pdf
+testmodel-plotall.png
+testmodel-plotall.svg
+testmodel.pdf
+testmodel.png
+testmodel.svg
+tmp.rst
+tmp.wiki
+VanDerPol.pdf
+VanDerPol.png
+VanDerPol.svg

doc/UsersGuide/source/githubreleases.py

@@ -7,7 +7,7 @@
 gh_auth = os.environ["GITHUB_AUTH"]
 g = Github(gh_auth)
 om = g.get_repo("OpenModelica/OpenModelica")
-fout = open("githubreleases.md","w")
+fout = open("githubreleases.md", "w", encoding="utf-8")
 
 for release in om.get_releases():
     if release.draft:
@@ -25,8 +25,8 @@
     print(release.title)
 fout.close()
 call(["pandoc", "--wrap=none", "-f", "gfm", "-t", "rst", "--base-header-level=2", "-o", "githubreleases.tmp.rst", "githubreleases.md"])
-with open("githubreleases.tmp.rst") as fin:
-    with open("githubreleases.tmp2.rst", "w") as fout:
+with open("githubreleases.tmp.rst", "r", encoding="utf-8") as fin:
+    with open("githubreleases.tmp2.rst", "w", encoding="utf-8") as fout:
         fout.write('''Major OpenModelica Releases
 """""""""""""""""""""""""""
 
@@ -37,4 +37,4 @@
         fout.write(fin.read())
         fout.write("\n")
         fout.write(".. include :: tracreleases.inc")
-os.rename("githubreleases.tmp2.rst", "githubreleases.rst")
+os.rename("githubreleases.tmp2.rst", "githubreleases.rst")