sphinx doc auto generation v3

Etienne Pallier
1 parent d9d66439
Showing 7 changed files with 67 additions and 24 deletions Show diff stats
Dockerfile
doc/doc_rst/make_rst_then_html
doc/doc_rst/requirements.txt
doc/doc_rst/source/index.rst
docker/HELP.md
install/requirements.txt
pyros.py
@@ -5,7 +5,9 @@ RUN apt-get update &amp;&amp; apt-get install -y \
     default-mysql-client \
     git \
     nano \
-    vim
+    vim \
+	# for PNG diagrams generation with pyreverse (pylint)
+	graphviz
  
 # Get IRAP self signed certificate
 RUN echo | openssl s_client -connect gitlab.irap.omp.eu:443 -servername gitlab.irap.omp.eu 2>/dev/null | openssl x509 > /etc/ssl/certs/gitlab.irap.omp.eu.crt
@@ -34,4 +36,4 @@ ENV PATH &quot;$PATH:/home/pyros_user/.local/bin&quot;
 RUN pip install --user click
  
 # installing packages required for PyROS
-RUN pip install --user -r ./install/requirements.txt
 \ No newline at end of file
+RUN pip install --user -r ./install/requirements.txt
@@ -25,7 +25,7 @@ pwd
 ######sphinx-apidoc -o source -a --separate --module-first --tocfile device_controller_package ../../src/device_controller
  
 # 3) pyros_django package
-sphinx-apidoc -f -o source/generated_api -a --separate --module-first --tocfile pyros_django_package ../../src/core/pyros_django
+######sphinx-apidoc -f -o source/generated_api -a --separate --module-first --tocfile pyros_django_package ../../src/core/pyros_django
 ##sphinx-apidoc -f -o source -a --separate --module-first --tocfile pyros_django_package ../../src/core/pyros_django
 #sphinx-apidoc -f -o source --tocfile pyros_django_package ../../src/core/pyros_django
  
 Sphinx
 sphinx-autodoc-typehints
-sphinx-pyreverse
  
 # Extensions
 autodocsumm
@@ -9,7 +8,24 @@ autodocsumm
 #alabaster
 sphinx-rtd-theme
  
-# Builder
+# Builder (pdf)
 rst2pdf
 #rstcheck
  
+# For pyreverse (included in pylint)
+pylint
+graphviz
+pygraphviz
+sphinx_pyreverse
+
+# Graphviz : for generating png diagrams from pyreverse
+# Par défaut, seuls deux formats de sortie sont possibles : dot et vcg.
+# Il est possible d'augmenter la quantité des formats de sortie avec l'installation de GraphViz
+# See https://graphviz.org/download
+# - Ubuntu & Debian :
+#sudo apt install graphviz
+# - Fedora & CentOS :
+#sudo yum install graphviz
+# - Mac :
+#brew install graphviz
+
@@ -55,7 +55,7 @@ See in the `Execution &amp; Configuration documentation - Observatory Configuration 
 4. PyROS API Source Code documentation
 --------------------------------------
  
-The PyROS :doc:`Packages, Classes, and Methods<generated_api/pyros_django_package>`
+.. The PyROS :doc:`Packages, Classes, and Methods<generated_api/pyros_django_package>`
  
  
  
@@ -84,7 +84,10 @@ See in the `Guitastro documentation &lt;../../../../vendor/guitastro/doc_rst/build/
     :caption: Contents:
  
     generated_api/codestyle_examples_package
-    generated_api/pyros_django_package
+
+.. generated_api/pyros_django_package
+
+
  
 .. comment    guitastro
  
@@ -53,6 +53,7 @@ To install the database and instantiate initial data.
 You should run this script the first time you are installing PyROS or if you want to reset your database according to the models and inject initial data.
  
 Before running this script, you should stop PyROS (website and other services) if it is running.
+
 3.2.4. PYROS_DOCKER_UPDATE
  
 This will update your project (by pulling the modification from the git repository), update the database structure (by running Django migrations), and update various diagrams.
@@ -27,7 +27,25 @@ sqlparse==0.4.2
 Twisted==21.7.0
 voevent-parse==1.0.3
 zope.interface==5.4.0
-# For DEV
+
+
+#
+# For Celery:
+#
+##celery==3.1.23
+##flower==0.9.2
+##amqp==1.4.9
+##amqplib==1.0.2
+##billiard==3.3.0.23
+##kombu==3.0.37
+##django-celery==3.1.17
+
+
+
+#
+# DEV only
+#
+
 django-debug-toolbar==3.2.2
 # Modifications 2021 :
 # removing plantuml because we need a unofficial version (maybe we could force to go back on an old version where the bug wasn't happening
@@ -42,19 +60,20 @@ PyYAML==6.0
 # For SP TAC Assignation
 matplotlib==3.4.3
 numpy==1.21.4
-# For Celery:
-##celery==3.1.23
-##flower==0.9.2
-##amqp==1.4.9
-##amqplib==1.0.2
-##billiard==3.3.0.23
-##kombu==3.0.37
-##django-celery==3.1.17
+
 # For working with GIT within Python
 GitPython==3.1.24
 # For working with date
 python-dateutil==2.8.2
+
+
+
+
+# TODO: a virer car dans fichier requirements guitastro dédié
+#
 # Celme / guitastro packages
+#
+
 # pypylon not available for 3.10 at 2021/11/10  (cf https://github.com/basler/pypylon#binary-installation)
 pypylon==1.7.4
 sep==1.2.0
@@ -527,7 +527,7 @@ def install_or_update(UPDATE: bool = False, packages_only: bool = False, databas
         except:
             pip = "pip" if IS_WINDOWS else "pip3"
             process = subprocess.Popen(
-                pip + " install --upgrade GitPython", shell=True)
+                pip + " install --user --upgrade GitPython", shell=True)
             process.wait()
             if process.returncode == 0:
                 # self.addExecuted(self.current_command, command)
@@ -716,7 +716,7 @@ def start(agent: str, configfile: str, observatory: str, unit: str):
         # TODO: "python -m pip" au lieu de "pip"
         pip = "pip" if IS_WINDOWS else "pip3"
         process = subprocess.Popen(
-            pip + " install --upgrade pykwalify", shell=True)
+            pip + " install --user --upgrade pykwalify", shell=True)
         process.wait()
         if process.returncode == 0:
             # self.addExecuted(self.current_command, command)
@@ -917,11 +917,11 @@ def stop(agent):
  
 def notused_update_python_packages_from_requirements():
     # 1) Upgrade pip (if new version available)
-    res = execProcessFromVenv("-m pip install --upgrade pip")
+    res = execProcessFromVenv("-m pip install --user --upgrade pip")
     if not res:
         return False
     # 2) Install only "not yet installed" python packages
-    res = execProcessFromVenv("-m pip install -r install/"+REQUIREMENTS)
+    res = execProcessFromVenv("-m pip install --user -r install/"+REQUIREMENTS)
     return res
  
  
@@ -945,6 +945,8 @@ def _update_plantuml_diags():
 def _update_api_doc():
     print(os.getcwd())
     DOC_RST_PATH = "doc/doc_rst/"
+    # 0) Upgrade pip if new version available
+    os.system(VENV_PYTHON + ' -m pip install --user --upgrade pip')
     # 1) install/update Sphinx requirements (only if not yet installed)
     venv_pip_install2(DOC_RST_PATH+'requirements.txt', '-r')
     # 2) make html doc from RST doc
@@ -1119,11 +1121,11 @@ def notused_install_required():
  
  
 def venv_pip_install(package_name: str, options: str = ''):
-    os.system(VENV_PIP + ' install ' + options + ' ' + package_name)
+    os.system(VENV_PIP + ' install --user ' + options + ' ' + package_name)
  
  
 def venv_pip_install2(package_name: str, options: str = ''):
-    os.system(VENV_PYTHON + ' -m ' + VENV_PIP + ' install '
+    os.system(VENV_PYTHON + ' -m ' + VENV_PIP + ' install --user '
               + options + ' ' + package_name)
  
  
@@ -1196,7 +1198,7 @@ def install_packages():
     print(Colors.LOG_BLUE + "-----------------------------Upgrade pip, wheel, and setuptools" +
           "-----------------------------"+END_OF_LINE + Colors.END)
     # Upgrade pip
-    os.system(VENV_PYTHON + ' -m pip install --upgrade pip')
+    os.system(VENV_PYTHON + ' -m pip install --user --upgrade pip')
     '''
     if (platform.system() == "Windows"):    
         os.system(venv + '\Scripts\python -m pip install --upgrade pip')
@@ -1209,7 +1211,7 @@ def install_packages():
     #os.system(VENV_PIP+' install --upgrade wheel')
     # Not working with python 3.8 (on 17/02/2022)
     # venv_pip_install('setuptools', '--upgrade')
-    os.system(VENV_PIP+' install setuptools==58')
+    os.system(VENV_PIP+' install --user setuptools==58')
  
     # Pip install required packages from REQUIREMENTS file
     print()