Add logging guideline section. (#23)

* Add logging guidelines.

* Add logging to the Guidelines section.

* Remove new line.

* Add images for the logging guideline.

* Add list of guidelines.

* Add the intersphinx extension.

* Fix Duplicate explicit target name.

* add logging example module

* ignore gitignore

* Fix typo.

* Why and when to log.

* Always log to share data.

* Add sphinx_toolbox in the doc requirements.

* Improve some comments in the logging example.

* Replace 'file' by 'stdout' for the stream.

* Add unit tests for the logging example module.

* add literalinclude

* Improve syntax.

* Move the test close to the module itself.

* Add a best practice section.

* Move the App filter under the best practices.

* Improve the app filter text.

* Remove the sys.path.append().

* Solve title conflict.

* Add Logger destructeur.

* Improve logging.Handler section.

* Use the tmpdir fixture.

* Improve the wrapping section.

* Update logging/test_pyansys_logging.py

Co-authored-by: Alex Kaszynski <[email protected]>

* Update logging/pyansys_logging.py

Co-authored-by: Alex Kaszynski <[email protected]>

* Update logging/test_pyansys_logging.py

Co-authored-by: Alex Kaszynski <[email protected]>

* Add the cleanup argument.

Co-authored-by: Alex Kaszynski <[email protected]>

Author: MaxJPRey

.gitignore

@@ -9,9 +9,12 @@ dist/*
 #########################
 *.egg-info/
 
-
+# Build docs and packages
 build/*
 doc/build/
 
 # virtual environment
-venv/
+venv/
+
+# sphinx autogen
+doc/source/documentation_style/api/*

doc/source/conf.py

@@ -1,12 +1,14 @@
 from datetime import datetime
 
+from pyansys_sphinx_theme import __version__, pyansys_logo_black
+
 # Project information
 project = 'PyAnsys Developers Guide'
-copyright = f'{datetime.now().year}, ANSYS'
-author = 'ANSYS, Inc.'
+copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
+author = "Ansys Inc."
 release = version = '0.1.dev0'
 
-html_logo = 'https://docs.pyansys.com/_static/pyansys-logo-black-cropped.png'
+html_logo = pyansys_logo_black
 html_theme = 'pyansys_sphinx_theme'
 
 html_theme_options = {
@@ -16,21 +18,31 @@
 
 # Sphinx extensions
 extensions = [
-    'sphinx.ext.todo',
+    "sphinx_copybutton",
+    'sphinx_toolbox.collapse',
     'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
 ]
 
+# Intersphinx mapping
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/dev", None),
+    # "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    # "numpy": ("https://numpy.org/devdocs", None),
+    # "matplotlib": ("https://matplotlib.org/stable", None),
+    # "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
+    # "pyvista": ("https://docs.pyvista.org/", None),
+}
+
 # The suffix(es) of source filenames.
 source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
 
-
-master_doc = 'index'
-
 latex_elements = {}
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/source/documentation_style/api/pyansys_sphinx_theme.samples.Complex.abs.rst

@@ -1,20 +1,21 @@
-Guidelines
+Guidelines and Best Practices
 #############################
-The purpose of this section is to highligh some common practices that
-can be applied to the entire PyAnsys project in order to remain consistent.
+This section describes and outlines several best practices that can be
+applied to PyAnsys libaries for the purpose of creating effective and
+efficient Python libraries to interface with Ansys products and
+services. These guidelines demonstrate how applications and complex
+services expose functionalities such as logging, data transfer, and
+Application APIs.
 
-One of the main objectives of PyAnsys libraries is to wrap (encapsulate) 
-data and methods within units of execution while hiding data or parameters 
-in protected variables.
-
-Those guidelines demonstrate how applications and complex services expose
-functionalities such as logging, data transfer...
+Table of Contents
+-----------------
 
 .. toctree::
-   :hidden:
-   :maxdepth: 3
+   :maxdepth: 2
 
    dev_practices
    app_interface_abstraction
-   service_abstraction
    data_transfer_and_representation
+   logging
+   service_abstraction
+