Utiliser l'ouitl de documentation sphinx
========================================

La documentation  officelle de Sphinx-doc
-----------------------------------------

`la documentation <https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information>`_

`des ressources pour sphinx <https://inspe-sciedu.gricad-pages.univ-grenoble-alpes.fr/reflexpro/res_sphinx.html>`_

Des liens pour la syntaxe 
-------------------------

`université de Grenoble <https://inspe-sciedu.gricad-pages.univ-grenoble-alpes.fr/reflexpro/syntaxe_sphinx.html/>`_ 
ou 

`la syntaxe rest <http://pdessus.fr/projets/reflexpro/html/syntaxe_rest.html#directives-html/>`_.
ou

`des informations avancées <https://gitlab.in2p3.fr/Thierry/PiscineJI/tree/master/Sphinx-doc>`_

`des  ajouter script js <https://sphinxawesome.xyz/how-to/customize/add-custom-js/>`_

Préparation de l'environnement sphinx
-------------------------------------

Mise en place en dur ...(non recommandé)

.. code-block:: console

    mkdir virtualenv
    python3 -m venv virtualenv
    source virtualenv/bin/activate
    #derriere un proxy non configure dans le système
    pip install --proxy http://10.255.5.210:3128  install sphinx
    # ajouter -U pour les upgrade 
    #Pour la documentation automatique des modules python
    pip install --proxy http://10.255.5.210:3128  sphinx-autodoc
    pip install --proxy http://10.255.5.210:3128  flask
    apt install mariadb-server
    pip install --proxy http://10.255.5.210:3128  -U setup-tools
    apt install python3-mysqldb pkg-config #eventuellement mariadb-dev mariadb-dev-compat
    
    pip install --proxy http://10.255.5.210:3128  mysql
	pip install mysql-connector-python
    apt install python3-flask
	apt install python3-setuptools
	apt install python3-xmltodict 
	#apt install python3-cas
	apt install python3-wtforms 

	#pour latex
    apt install texlive-latex-recommended
    apt install texlive-fonts-recommended
	apt install tex-gyre 
	apt install texlive-latex-extra
	apt install latexmk
	#plus ...

# texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),

#texlive-lang-greek for Greek (and also then cm-super if using the default fonts),

#texlive-xetex if latex_engine is 'xelatex',

#texlive-luatex if latex_engine is 'lualatex',

#fonts-freefont-otf if latex_engine is either 'xelatex' or 'lualatex'.

Création d'une documentation sphinx
-----------------------------------
.. code-block:: console

	sphinx-quickstart activites-pedagogiques
	vim activites-pedagogiques/sources/index.rst
	cd activites-pedagogiques
	make html


ajouter l'auto-analyses d'un module:

 * Dans conf.py: 

	.. code-block:: console
	
		import os
		#chemin contenant le ou les modules
		sys.path.insert(0,os.path.abspath('/var/www/serveur/'))

		extensions = [
			'sphinx.ext.autodoc',
		]

  * Dans un fichier rst :

	.. code-block:: console

		Submodules
		----------

		Module activités
		----------------

		.. automodule:: blueprints.Activites.Activites
		:members:
		:undoc-members:
		:show-inheritance:


		Module Activites BDD:
		---------------------

		.. automodule:: blueprints.Activites.ActivitesBDD
		:members:
		:undoc-members:
		:show-inheritance:

Utiliser une variable
---------------------

  * Commencer par installer l'extension 

	.. code-block:: console

		pip install Sphinx-Substitution-Extensions


  * Dans le conf.py (il y a certainement mieux !)

	.. code-block:: console

		mon_appli = 'serveur'
		rst_prolog = """
		.. |mon_appli| replace:: serveur
		"""
		
		sys.path.insert(0,os.path.abspath('/var/www/'+mon_appli+'/'))



		extensions = [
			'sphinx.ext.autodoc',
    		'sphinx_substitution_extensions',
			../..
		]

  * Dans un fichier rst , par exemple usagebdservice.rst 

	.. code-block:: console

		Utiliser |mon_appli|
		====================

	Affichera Utiliser serveur


Dans un code block

	.. code-block:: bash
		:substitutions:
		
		echo "|mon_appli| une appli pedagogique"
	

Inline :substitution-code:

	:substitution-code:`echo "|mon_appli| informations générales "` 

substitution-download

	:substitution-download:`les codes des exemples ci-dessus pour |mon_appli|' <|mon_appli|_manuscript.txt>` 

	
.. toctree::
   :maxdepth: 2

   pip-requirements
   packager-installer