Merge pull request #2 from phaseportrait/release/1.2.0

Release/1.2.0

.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: PyPi and Docs
+
+on:
+  push:
+    branches: 
+    - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-pypi:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: master
+        token: ${{ github.token }}
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        git config user.name github-actions
+        git config user.email github-actions@github.com
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish package to PyPi
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        repository_url: https://upload.pypi.org/legacy/ 
+
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: master
+        token: ${{ github.token }}
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        git config user.name github-actions
+        git config user.email github-actions@github.com
+        python -m pip install --upgrade pip
+        pip install build
+        pip install mkdocs
+        pip install mkdocstrings[python]>=0.18
+        pip install mkdocs-gen-files
+        pip install mkdocs-material
+        pip install mkdocs-literate-nav
+        pip install Pygments>=2.12
+
+    - name: Build documentation
+      run: |
+        python3 docs/generate_reference_docs.py
+        mkdocs build
+
+    - name: Update github-pages
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: site

MANIFEST.in

@@ -1,4 +1,9 @@
 include README_no_imgs.md
 include README.md
-recursive-include docs *
-recursive-include examples *
+include setup.cfg
+include setup.py
+
+graft phaseportrait/*
+graft examples/*
+
+prune */__pycache__

docs/SUMMARY.md

@@ -0,0 +1,29 @@
+* reference
+    * phaseportrait
+        * [Cobweb](reference/phaseportrait/Cobweb.md)
+        * [Map1D](reference/phaseportrait/Map1D.md)
+        * [PhasePortrait2D](reference/phaseportrait/PhasePortrait2D.md)
+        * [PhasePortrait3D](reference/phaseportrait/PhasePortrait3D.md)
+        * [PhasePortraitManager](reference/phaseportrait/PhasePortraitManager.md)
+        * [Trajectories2D](reference/phaseportrait/Trajectories2D.md)
+        * [Trajectories3D](reference/phaseportrait/Trajectories3D.md)
+        * exceptions
+            * [exceptions](reference/phaseportrait/exceptions/exceptions.md)
+        * generators_base
+            * [generator_base](reference/phaseportrait/generators_base/generator_base.md)
+        * maps
+            * [map](reference/phaseportrait/maps/map.md)
+        * nullclines
+            * [nullclines](reference/phaseportrait/nullclines/nullclines.md)
+        * sliders
+            * [sliders](reference/phaseportrait/sliders/sliders.md)
+        * streamlines
+            * [size_gradient](reference/phaseportrait/streamlines/size_gradient.md)
+            * [streamlines_base](reference/phaseportrait/streamlines/streamlines_base.md)
+            * [velocity_color_gradient](reference/phaseportrait/streamlines/velocity_color_gradient.md)
+        * trajectories
+            * [rungekutta](reference/phaseportrait/trajectories/rungekutta.md)
+            * [trajectory](reference/phaseportrait/trajectories/trajectory.md)
+        * utils
+            * [manager](reference/phaseportrait/utils/manager.md)
+            * [utils](reference/phaseportrait/utils/utils.md)

docs/generate_reference_docs.py

@@ -0,0 +1,85 @@
+# Copyright 2023 Unai Lería Fortea & Pablo Vizcaíno García
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+# http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generate the code reference pages and navigation. Ty mkdocstrings"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+LICENSE = """<!-- Copyright 2023 PhasePortriat
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License. -->
+"""
+
+# import shutil
+
+# shutil.copy("README.md", "docs/index.md")
+# shutil.copy("LICENSE", "docs/LICENSE.md")
+
+for path in sorted(Path("phaseportrait").rglob("*.py")):
+    module_path = path.with_suffix("")
+    doc_path = path.with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        continue
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[("reference", *parts)] = full_doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(LICENSE)
+        fd.write(f":::{ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, Path("../") / path)
+
+
+for path in sorted(list(Path("examples").rglob("*.md"))):
+    example_name = path.with_suffix("")
+    doc_path = path.with_suffix(".md")
+    full_doc_path = Path(doc_path)
+
+    parts = tuple(example_name.parts)
+
+    nav[("examples", *parts)] = full_doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(''.join([line for line in open(path, 'r').readlines()]))
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, Path("../") / path)
+
+with mkdocs_gen_files.open("SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
+

docs/cobweb.md → docs/reference/legacy/cobweb.md

@@ -93,7 +93,7 @@ Adds a slider for changing initial value on a cobweb plot.
 
 **Key Arguments**
 
-* valinit : numeric
+* valinit : float
 
     Initial position. Default value is the same as initial position given when initializing Cobweb object.
 
@@ -128,7 +128,7 @@ LogisticCobweb.plot()
 
 This will output the following plots:
 
-![image](imgs/doc_examples/cobweb_exampe.png)
+![image](../../imgs/doc_examples/cobweb_exampe.png)
 
 * [See more Cobweb examples.](mapsandcobweb_examples.md)
 

docs/map1d.md → docs/reference/legacy/map1d.md

@@ -201,7 +201,7 @@ Logistic_Map.plot_over_variable('r', [2,3.9], 0.005,
 
 fig, ax = Logistic_Map.plot()
 ```
-![image](imgs/doc_examples/map_example.png)
+![image](../../imgs/doc_examples/map_example.png)
 
 * [See more Map1D examples.](mapsandcobweb_examples.md)
 

docs/mapsandcobweb_examples.md → docs/reference/legacy/mapsandcobweb_examples.md

@@ -30,7 +30,7 @@ LogisticCobweb = Cobweb(Logistic, 0.1, [0,1], yrange=[0,1])
 fig1, ax1, fig2, ax2 = LogisticCobweb.plot()
 ```
 
-![image](imgs/map&cobweb_examples/Figure_1.png)
+![image](../../imgs/map&cobweb_examples/Figure_1.png)
 
 We can use returned objects to change plot's properties, such as title, xlabel, ylabel... We can also pass `Title`, `xlabel` and `ylabel` as key arguments when creating the *Cobweb* object instance for changing the cobweb plot's labels, but not the time series plot.
 
@@ -71,7 +71,7 @@ fig1, ax1, fig2, ax2 = LogisticCobweb.plot()
 
 ax2.set_title('Logistic map time series')
 ```
-![image](imgs/map&cobweb_examples/Figure_2.png)
+![image](../../imgs/map&cobweb_examples/Figure_2.png)
 
 # Map1D plots
 
@@ -98,7 +98,7 @@ Log1.plot_over_variable('r', [2,3.9], 0.005)
 
 fig, ax = Log1.plot()
 ```
-![image](imgs/map&cobweb_examples/Figure_11.png)
+![image](../../imgs/map&cobweb_examples/Figure_11.png)
 
 As you can see, this is a mess. That happended because the first steps are not in a stable cycle, and must be deleted.
 
@@ -113,7 +113,7 @@ Log2.plot_over_variable('r', [2,3.9], 0.005)
 
 fig, ax = Log2.plot()
 ```
-![image](imgs/map&cobweb_examples/Figure_12.png)
+![image](../../imgs/map&cobweb_examples/Figure_12.png)
 
 Note: in some cases the graph is very dependant of the initial position. In the method `plot_over_variable` there is a karg for specifying the initial position: `plot_over_variable(initial_x=... )`.
 
@@ -133,7 +133,7 @@ Log3.plot_over_variable('r', [2,3.9], 0.005)
 fig, ax = Log3.plot()
 ```
 
-![image](imgs/map&cobweb_examples/Figure_13.png)
+![image](../../imgs/map&cobweb_examples/Figure_13.png)
 
 ## Time series
 
@@ -145,7 +145,7 @@ Log4.plot_trajectory(100, dF_args={'r':3.40, 'p':1.35}, initial_x=0.5)
 fig, ax = Log4.plot()
 ```
 
-![image](imgs/map&cobweb_examples/Figure_14.png)
+![image](../../imgs/map&cobweb_examples/Figure_14.png)
 
 # Some more examples
 

docs/nullclines.md → docs/reference/legacy/nullclines.md

@@ -95,5 +95,5 @@ example.add_nullclines(precision=0.05)
 example.plot()
 ```
 
-![image](imgs/doc_examples/nullclines_example.png)
+![image](../../imgs/doc_examples/nullclines_example.png)
 

docs/phaseportrait2d.md → docs/reference/legacy/phaseportrait2d.md

@@ -26,7 +26,7 @@ Gives the option to represent a 2D phase portrait given a [dF](dFfunction.md) fu
 
 * **Density** : float, default=1
 
-    Number of elements in the arrows grid plot.
+    [Deprecated] Number of elements in the arrows grid plot.
 
 * **Polar** : bool, default=False
 
@@ -100,6 +100,24 @@ Plots nullclines of the system given by dF function. For more info, see [Nullcli
 
 * None
 
+
+### *PhasePortrait2D*.colorbar
+> *PhasePortrait2D*.**colorbar**(*toggle=True*)
+
+
+Adds a colorbar for speed.
+
+**Parameters**
+
+* toggle : bool, default=True
+
+    If `True` colorbar is visible.
+
+**Returns**
+
+* None
+
+
 # Defining Range
 
 1. A single number. In this case the range is defined from zero to the given number in both axes.
@@ -124,6 +142,6 @@ example.add_nullclines()
 example.plot()
 ``` 
 
-![image](imgs/doc_examples/pp2d_example.png)
+![image](../../imgs/doc_examples/pp2d_example.png)
 
 * [Click here to see more examples.](phaseportrait2d_examples.md)