From d75602f9f3136a74dcfa8792604c5187c3a3e430 Mon Sep 17 00:00:00 2001 From: L-Nafaryus Date: Wed, 25 Aug 2021 21:48:02 +0500 Subject: [PATCH] Mod: documentation improved --- INSTALL.rst | 61 +++ README.rst | 20 +- anisotropy/core/cli.py | 20 - docs/source/INSTALL.rst | 61 +++ docs/source/anisotropy.rst | 2 +- docs/source/conf.py | 3 + docs/source/index.rst | 1 + docs/source/modules.rst | 9 - docs/source/notes.rst | 7 + docs/source/notes/database.rst | 6 + {notes => docs/source/notes}/images.rst | 6 +- {notes => docs/source/notes}/mesh.rst | 1 - {notes => docs/source/notes}/netgen.rst | 5 +- {notes => docs/source/notes}/of-tools.rst | 2 + docs/source/notes/sphinx.rst | 8 + docs/source/notes/structure.rst | 6 + docs/source/setup.rst | 7 - docs/source/static/er-diagram | 591 ++++++++++++++++++++++ docs/source/static/style.css | 3 + docs/source/tests.rst | 29 -- notes/sphinx.rst | 9 - requirements.txt | 1 + 22 files changed, 769 insertions(+), 89 deletions(-) delete mode 100644 docs/source/modules.rst create mode 100644 docs/source/notes.rst create mode 100644 docs/source/notes/database.rst rename {notes => docs/source/notes}/images.rst (75%) rename {notes => docs/source/notes}/mesh.rst (99%) rename {notes => docs/source/notes}/netgen.rst (99%) rename {notes => docs/source/notes}/of-tools.rst (72%) create mode 100644 docs/source/notes/sphinx.rst create mode 100644 docs/source/notes/structure.rst delete mode 100644 docs/source/setup.rst create mode 100644 docs/source/static/er-diagram create mode 100644 docs/source/static/style.css delete mode 100644 docs/source/tests.rst delete mode 100644 notes/sphinx.rst diff --git a/INSTALL.rst b/INSTALL.rst index cd7a81d..9810407 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -1,3 +1,64 @@ Installation ============ +Recommended way is to install a package in the virtual environment. +Just create and activate python virtual environment: + +.. code-block:: bash + + $ python -m venv env + $ source env/bin/activate + +and run pip inside (upgrade pip if you need): + +.. code-block:: bash + + (env) $ python -m pip install --upgrade pip + (env) $ python -m pip install . + +External applications +--------------------- + +Anisotropy project requires ``Salome`` and ``OpenFOAM`` executables be ``PATH``. + +1. For simple way you can use next commands (each time): + +.. code-block:: bash + + $ export PATH="${PATH}:${HOME}/PATH/TO/SALOME/DIRECTORY" + $ source "${HOME}/PATH/TO/OPENFOAM/DIRECTORY/etc/bashrc" + +2. Or modify file ``conf/bashrc`` in project directory (example) + +.. code-block:: bash + + export PATH="${PATH}:${HOME}/programs/salome/SALOME-9.7.0-MPI" + source "${HOME}/programs/OpenFOAM/OpenFOAM-v2012/etc/bashrc" + +and source it (each time): + +.. code-block:: bash + + $ source conf/bashrc + +3. The best way is modify file like in step 2 and append it to virtual environment activate script: + +.. code-block:: bash + + $ cat conf/bashrc | tee -a env/bin/activate + +So next time you just need to ``source env/bin/activate`` and you completely ready. + +Building documentaion +--------------------- + +For building documentaion you must sure that all requirements installed. +Project uses ``Sphinx`` and ``make`` for building: + +.. code-block:: bash + + $ source env/bin/activate + (env) $ cd docs + (env) $ make html + + diff --git a/README.rst b/README.rst index 9644ff0..7505851 100644 --- a/README.rst +++ b/README.rst @@ -1,22 +1,24 @@ anisotropy -=============== +========== Requirements ------------ -* python 3.5> -* OpenFOAM -* SALOME -* ParaView +.. csv-table:: Requirements + :header: "Software", "Used version", "Recommended version" -Running -------- + "Python", "3.9.6", "> 3.6" + "Salome", "9.7.0", "> 9.6.0" + "OpenFOAM", "v2012", "" -*in progress* +Installation +------------ + +For installation guide see ``INSTALL``. License ------- GNU GPLv3 -For more information see ``LICENSE`` file in this repository. +For more information see ``LICENSE``. diff --git a/anisotropy/core/cli.py b/anisotropy/core/cli.py index 3c01109..a6712e0 100644 --- a/anisotropy/core/cli.py +++ b/anisotropy/core/cli.py @@ -203,26 +203,6 @@ def computemesh(root, type, direction, theta): model.genmesh() - -@anisotropy.command( - help = """Build documentation - - TARGET is the builder to use (default: html) - """ -) -@click.argument( - "target", - default = "html" -) -def docs(target): - from sphinx.cmd.make_mode import run_make_mode - from anisotropy import env - - sourcepath = os.path.join(env["DOCS"], "source") - buildpath = os.path.join(env["DOCS"], "build") - - run_make_mode([target, sourcepath, buildpath]) - ### # CLI entry ## diff --git a/docs/source/INSTALL.rst b/docs/source/INSTALL.rst index cd7a81d..9810407 100644 --- a/docs/source/INSTALL.rst +++ b/docs/source/INSTALL.rst @@ -1,3 +1,64 @@ Installation ============ +Recommended way is to install a package in the virtual environment. +Just create and activate python virtual environment: + +.. code-block:: bash + + $ python -m venv env + $ source env/bin/activate + +and run pip inside (upgrade pip if you need): + +.. code-block:: bash + + (env) $ python -m pip install --upgrade pip + (env) $ python -m pip install . + +External applications +--------------------- + +Anisotropy project requires ``Salome`` and ``OpenFOAM`` executables be ``PATH``. + +1. For simple way you can use next commands (each time): + +.. code-block:: bash + + $ export PATH="${PATH}:${HOME}/PATH/TO/SALOME/DIRECTORY" + $ source "${HOME}/PATH/TO/OPENFOAM/DIRECTORY/etc/bashrc" + +2. Or modify file ``conf/bashrc`` in project directory (example) + +.. code-block:: bash + + export PATH="${PATH}:${HOME}/programs/salome/SALOME-9.7.0-MPI" + source "${HOME}/programs/OpenFOAM/OpenFOAM-v2012/etc/bashrc" + +and source it (each time): + +.. code-block:: bash + + $ source conf/bashrc + +3. The best way is modify file like in step 2 and append it to virtual environment activate script: + +.. code-block:: bash + + $ cat conf/bashrc | tee -a env/bin/activate + +So next time you just need to ``source env/bin/activate`` and you completely ready. + +Building documentaion +--------------------- + +For building documentaion you must sure that all requirements installed. +Project uses ``Sphinx`` and ``make`` for building: + +.. code-block:: bash + + $ source env/bin/activate + (env) $ cd docs + (env) $ make html + + diff --git a/docs/source/anisotropy.rst b/docs/source/anisotropy.rst index 255eea7..9e7eb87 100644 --- a/docs/source/anisotropy.rst +++ b/docs/source/anisotropy.rst @@ -1,4 +1,4 @@ -anisotropy package +Anisotropy package ================== Subpackages diff --git a/docs/source/conf.py b/docs/source/conf.py index f56a150..b00c20b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,3 +52,6 @@ html_theme = 'sphinx_rtd_theme' # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['static'] +html_css_files = [ + "static/style.css" +] diff --git a/docs/source/index.rst b/docs/source/index.rst index 2495dd9..c6807b0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ Welcome to anisotropy's documentation! INSTALL anisotropy + notes .. include:: ../../README.rst diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index 923dea1..0000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,9 +0,0 @@ -anisotropy -========== - -.. toctree:: - :maxdepth: 4 - - anisotropy - setup - tests diff --git a/docs/source/notes.rst b/docs/source/notes.rst new file mode 100644 index 0000000..8002b31 --- /dev/null +++ b/docs/source/notes.rst @@ -0,0 +1,7 @@ +Notes +===== + +.. toctree:: + :glob: + + notes/* diff --git a/docs/source/notes/database.rst b/docs/source/notes/database.rst new file mode 100644 index 0000000..ab7dce8 --- /dev/null +++ b/docs/source/notes/database.rst @@ -0,0 +1,6 @@ +Database hierarchy +================== + +Current anisotropy database hierarchy: + +.. image:: ../static/er-diagram.png diff --git a/notes/images.rst b/docs/source/notes/images.rst similarity index 75% rename from notes/images.rst rename to docs/source/notes/images.rst index 1530d21..f74affd 100644 --- a/notes/images.rst +++ b/docs/source/notes/images.rst @@ -1,11 +1,15 @@ Usefull command for making images ================================= +For database ER diagram (``peewee_erd``): + .. code-block:: python from peewee_erd import draw draw(["anisotropy/core/models.py"], "docs/source/static/er-diagram.svg", "#333333", "#eeeeee", 12, False, False) +For project structure (``pydeps``): + .. code-block:: bash - pydeps anisotropy --max-bacon 2 --cluster -o docs/source/static/deps.svg --noshow + pydeps anisotropy --max-bacon 2 --cluster -o docs/source/static/deps.svg -T svg --noshow diff --git a/notes/mesh.rst b/docs/source/notes/mesh.rst similarity index 99% rename from notes/mesh.rst rename to docs/source/notes/mesh.rst index 7ed145c..08e0a07 100644 --- a/notes/mesh.rst +++ b/docs/source/notes/mesh.rst @@ -11,7 +11,6 @@ The main goal for the current meshes is to achieve the following points: Example: .. code-block:: python - :linenos: shape, groups = simple(0.28, True, [1, 0, 0]) lengths = [ geompy.BasicProperties(edge)[0] for edge in geompy.SubShapeAll(shape, geompy.ShapeType["EDGE"]) ] diff --git a/notes/netgen.rst b/docs/source/notes/netgen.rst similarity index 99% rename from notes/netgen.rst rename to docs/source/notes/netgen.rst index 3422faf..98ee12d 100644 --- a/notes/netgen.rst +++ b/docs/source/notes/netgen.rst @@ -1,6 +1,5 @@ -=============== -Mesh generation -=============== +Salome Netgen parameters +======================== .. ``netgen parameters`` minSize diff --git a/notes/of-tools.rst b/docs/source/notes/of-tools.rst similarity index 72% rename from notes/of-tools.rst rename to docs/source/notes/of-tools.rst index 32d0648..23b36e8 100644 --- a/notes/of-tools.rst +++ b/docs/source/notes/of-tools.rst @@ -1,3 +1,5 @@ +OpenFOAM usefull utils +====================== - createPatch - polyDualMesh diff --git a/docs/source/notes/sphinx.rst b/docs/source/notes/sphinx.rst new file mode 100644 index 0000000..d50db14 --- /dev/null +++ b/docs/source/notes/sphinx.rst @@ -0,0 +1,8 @@ +Sphinx apidoc and build +======================= + +.. code-block:: bash + + $ sphinx-apidoc -o docs/source/ ./ + $ cd docs + $ make html diff --git a/docs/source/notes/structure.rst b/docs/source/notes/structure.rst new file mode 100644 index 0000000..0f2147c --- /dev/null +++ b/docs/source/notes/structure.rst @@ -0,0 +1,6 @@ +Anisotropy package structure +============================ + +Current anisotropy project structure: + +.. image:: ../static/structure.png diff --git a/docs/source/setup.rst b/docs/source/setup.rst deleted file mode 100644 index 552eb49..0000000 --- a/docs/source/setup.rst +++ /dev/null @@ -1,7 +0,0 @@ -setup module -============ - -.. automodule:: setup - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/static/er-diagram b/docs/source/static/er-diagram new file mode 100644 index 0000000..0c8f58b --- /dev/null +++ b/docs/source/static/er-diagram @@ -0,0 +1,591 @@ +digraph erd { + fontname = "Helvetica" + fontsize = 12 + splines = true + node [ + shape = "plaintext" + ] + + "BaseModel" + [label=< + + + + ''' + +
+ + BaseModel +
+ id + + AutoField +
+ >] + + "Flow" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + Flow +
+ flow_id + + AutoField +
+ structure_id + + ForeignKeyField +
+ scale + + ListField +
+ pressure + + JSONField +
+ velocity + + JSONField +
+ transportProperties + + JSONField +
+ >] + + "FlowApproximation" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + FlowApproximation +
+ flow_approximation_id + + AutoField +
+ flow_id + + ForeignKeyField +
+ pressure + + JSONField +
+ velocity + + JSONField +
+ transportProperties + + JSONField +
+ >] + + "FlowResult" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + FlowResult +
+ flowresult_id + + AutoField +
+ flow_id + + ForeignKeyField +
+ flowRate + + FloatField +
+ status + + TextField +
+ calculationTime + + TimeField +
+ >] + + "Mesh" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + Mesh +
+ mesh_id + + AutoField +
+ structure_id + + ForeignKeyField +
+ maxSize + + FloatField +
+ minSize + + FloatField +
+ fineness + + IntegerField +
+ growthRate + + FloatField +
+ nbSegPerEdge + + FloatField +
+ nbSegPerRadius + + FloatField +
+ chordalErrorEnabled + + BooleanField +
+ chordalError + + FloatField +
+ secondOrder + + BooleanField +
+ optimize + + BooleanField +
+ quadAllowed + + BooleanField +
+ useSurfaceCurvature + + BooleanField +
+ fuseEdges + + BooleanField +
+ checkChartBoundary + + BooleanField +
+ viscousLayers + + BooleanField +
+ thickness + + FloatField +
+ numberOfLayers + + IntegerField +
+ stretchFactor + + FloatField +
+ isFacesToIgnore + + BooleanField +
+ facesToIgnore + + ListField +
+ extrusionMethod + + TextField +
+ >] + + "MeshResult" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + MeshResult +
+ meshresult_id + + AutoField +
+ mesh_id + + ForeignKeyField +
+ surfaceArea + + FloatField +
+ volume + + FloatField +
+ elements + + IntegerField +
+ edges + + IntegerField +
+ faces + + IntegerField +
+ volumes + + IntegerField +
+ tetrahedrons + + IntegerField +
+ prisms + + IntegerField +
+ pyramids + + IntegerField +
+ status + + TextField +
+ calculationTime + + TimeField +
+ >] + + "Structure" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + Structure +
+ structure_id + + AutoField +
+ type + + TextField +
+ direction + + ListField +
+ theta + + FloatField +
+ r0 + + FloatField +
+ L + + FloatField +
+ radius + + FloatField +
+ filletsEnabled + + BooleanField +
+ fillets + + FloatField +
+ >] + + "SubMesh" + [label=< + + + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + + ''' + +
+ + SubMesh +
+ submesh_id + + AutoField +
+ mesh_id + + ForeignKeyField +
+ name + + TextField +
+ maxSize + + FloatField +
+ minSize + + FloatField +
+ fineness + + IntegerField +
+ growthRate + + FloatField +
+ nbSegPerEdge + + FloatField +
+ nbSegPerRadius + + FloatField +
+ chordalErrorEnabled + + BooleanField +
+ chordalError + + FloatField +
+ secondOrder + + BooleanField +
+ optimize + + BooleanField +
+ quadAllowed + + BooleanField +
+ useSurfaceCurvature + + BooleanField +
+ fuseEdges + + BooleanField +
+ checkChartBoundary + + BooleanField +
+ >] + + + "Flow":"structure_id" -> "Structure":"structure_id" + [arrowhead=empty, arrowtail=none, dir=both]; + + "FlowApproximation":"flow_id" -> "Flow":"flow_id" + [arrowhead=empty, arrowtail=none, dir=both]; + + "FlowResult":"flow_id" -> "Flow":"flow_id" + [arrowhead=empty, arrowtail=none, dir=both]; + + "Mesh":"structure_id" -> "Structure":"structure_id" + [arrowhead=empty, arrowtail=none, dir=both]; + + "MeshResult":"mesh_id" -> "Mesh":"mesh_id" + [arrowhead=empty, arrowtail=none, dir=both]; + + "SubMesh":"mesh_id" -> "Mesh":"mesh_id" + [arrowhead=empty, arrowtail=none, dir=both]; + + +} diff --git a/docs/source/static/style.css b/docs/source/static/style.css new file mode 100644 index 0000000..940f785 --- /dev/null +++ b/docs/source/static/style.css @@ -0,0 +1,3 @@ +svg { + width: 100px; +} diff --git a/docs/source/tests.rst b/docs/source/tests.rst deleted file mode 100644 index 965eea2..0000000 --- a/docs/source/tests.rst +++ /dev/null @@ -1,29 +0,0 @@ -tests package -============= - -Submodules ----------- - -tests.anisotropy\-cli module ----------------------------- - -.. automodule:: tests.anisotropy-cli - :members: - :undoc-members: - :show-inheritance: - -tests.test\_anisotropy module ------------------------------ - -.. automodule:: tests.test_anisotropy - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: tests - :members: - :undoc-members: - :show-inheritance: diff --git a/notes/sphinx.rst b/notes/sphinx.rst deleted file mode 100644 index 642f90e..0000000 --- a/notes/sphinx.rst +++ /dev/null @@ -1,9 +0,0 @@ -sphinx -====== - -.. code_block:: bash - :lineos: - - sphinx-apidoc -o docs/source/ ./ - cd docs - make html diff --git a/requirements.txt b/requirements.txt index f5b783a..0eb6907 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ +wheel numpy pyquaternion toml