Repository: pydap/pydap (python)

Issue:
set the documentation environment to use pydap installled from local branch
To improve documentation practices, I think the docs/en/environment.yml (and similarly the docs/es/environment.yml) file should install pydap in development mode (is this possible?), or not install pydap, making the user to install pydap manually in development mode, or enable the build.sh script to install pydap in development mode.


Either one of this scenarios will ensure that the documentation is build using the latest commits (during the development process) and therefore catching potential errors.



### Another improvement
there are two identical environment.yml files - one on the docs/en/ and the other on docs/es. This is a residual from copying and translating the original documentation from English into Spanish. But we only need one .yml file - must erase the copy and place it in a neutral location (parent `docs/` folder).


Pull request description:
Backwards compat
<!-- Thank you very much for your hard work and contribution! -->

The following Pull Request:

- [x] Provides backwards/forwards compatibility by adding a deprecation warning but enabling the use of dimensions/dims as described in  #485 #497 
- [x] Tests are added to demonstrate the new or fixed behavior, and all tests pass
on a local environment.
- [x] also closes #499 and #501 which do not require testing


Patch:
diff --git a/docs/en/_config.yml b/docs/en/_config.yml
index e731048..f5cd711 100644
--- a/docs/en/_config.yml
+++ b/docs/en/_config.yml
@@ -31,9 +31,6 @@ sphinx:
     html_theme_options:
       navigation_with_keys: false
 
-# Add a bibtex file so that we can create citations
-bibtex_bibfiles:
-- references.bib
 
 # Information about where the book exists on the web
 repository:
diff --git a/docs/en/contribute/contr_docs.md b/docs/en/contribute/contr_docs.md
index a43f1d8..e83be4b 100644
--- a/docs/en/contribute/contr_docs.md
+++ b/docs/en/contribute/contr_docs.md
@@ -24,23 +24,17 @@ conda activate pydap_docs
 ```{note}
 If you already have `mamba` installed, you can replace all `conda` in the commands with `mamba`.
 ```
-
-The `docs/environment.yml` file provides a ready-to-use environment (it installs `pydap-server`). However, if you have made new changes to the code, we recommend installing pydap in `dev` mode and making sure that all notebooks properly build.
+3. Install `pydap` in `developer` mode, to make sure that all notebooks are properly built. To do install in dev mode, run
 
 ```shell
 pip install -e .
 ```
-or to install `pydap` directly from the main branch:
-
-```shell
-pip install --upgrade git+https://github.com/pydap/pydap.git
-```
 
-3. Create a new branch, and set its upstream and use git (see [steps 3 and 4 from contributing to the code](contr_cod.md))
+4. Create a new branch, and set its upstream and use git (see [steps 3 and 4 from contributing to the code](contr_cod.md))
 
-4. The documentation is now split into two source files, one in English (you can find it in: `docs/en`), and one in Spanish (los puedes encontrar aqui `docs/es`). Depending on which version of the documentation you are contributing, you can modify the source files.
+5. The documentation is now split into two source files, one in English (you can find it in: `docs/en`), and one in Spanish (los puedes encontrar aqui `docs/es`). Depending on which version of the documentation you are contributing, you can modify the source files.
 
-5. Once you have made changes to the source files of the documentation (either in `docs/en` or `docs/es`), use the `build.sh` to clean and build `html` documentation files (you may need to make `build.sh`1= executable with `chmod +x `)
+6. Once you have made changes to the source files of the documentation (either in `docs/en` or `docs/es`), use the `build.sh` to clean and build `html` documentation files (you may need to make `build.sh`1= executable with `chmod +x `)
 ```shell
 cd docs
 chmod +x build.sh
@@ -52,7 +46,7 @@ Many of the tutorial examples in the documentation require EDL Authentication vi
 ```
 Depending on how many changes you have done to the documentation, this last step may take a while. It also depends on the type of files added to the documentation (`ipynb` are slower to build).
 
-6. Once the build process is finished, you can inspect the locally built html files. The `build.sh` creates a redirect at the base of the built html files. Thus, to open the English documentation execute
+7. Once the build process is finished, you can inspect the locally built html files. The `build.sh` creates a redirect at the base of the built html files. Thus, to open the English documentation execute
 ```shell
 open _build/html/index.html
 ```
@@ -69,9 +63,9 @@ Make sure to check that **ALL** notebooks were successfully built.
 The documentation will have a toggle to manually switch between the English and Spanish versions.
 ```
 
-7. Push all changes and create a PR. `PyDAP` follows the recommendations of keeping the `source` files on `main`, and the `build` files on the `gh-pages` branch.
+8. Push all changes and create a PR. `PyDAP` follows the recommendations of keeping the `source` files on `main`, and the `build` files on the `gh-pages` branch.
 ```{note}
 Do not include passwords or tokens. You are only submitting `source` files.
 ```
 
-8. Once a maintaner of `PyDAP` has approved your PR it will get merged into `main`. The maintainer of `PyDAP` can publish the documentation and update the `gh-pages` branch. Broadly, the steps to publish the documentation (i.e. rebuild the `gh-pages` branch) are detailed and described here: https://jupyterbook.org/en/stable/start/publish.html.
+9. Once a maintaner of `PyDAP` has approved your PR it will get merged into `main`. The maintainer of `PyDAP` can publish the documentation and update the `gh-pages` branch. Broadly, the steps to publish the documentation (i.e. rebuild the `gh-pages` branch) are detailed and described here: https://jupyterbook.org/en/stable/start/publish.html.
diff --git a/docs/en/environment.yml b/docs/en/environment.yml
deleted file mode 100644
index 4173be7..0000000
--- a/docs/en/environment.yml
+++ /dev/null
@@ -1,12 +0,0 @@
-name: pydap_docs
-channels:
-- conda-forge
-dependencies:
-- python=3.11
-- pydap-server
-- jupyter-book
-- jupyterlab
-- matplotlib
-- cartopy
-- xarray
-- dask
diff --git a/docs/en/how_to_install.md b/docs/en/how_to_install.md
index cd3396c..a9abd36 100644
--- a/docs/en/how_to_install.md
+++ b/docs/en/how_to_install.md
@@ -34,7 +34,7 @@ We recommend to use package installation managers like `conda`/`mamba`. This app
 
 ## Dependencies
 ### Minimal Required
-The following are required to run pydap as a client.
+The following are required to run `pydap` as a client.
 
 - `python>=3.10`
 - `numpy`
@@ -44,13 +44,15 @@ The following are required to run pydap as a client.
 - `beautifulsoup4`
 - `lxml`
 - `Webob`
--
+
+These are install with every `pydap` installation.
+
 ## Reproducible (conda) environments
 
 You can easily use conda to install `pydap` or `pydap-server`, along with any optional packages for sharing a reproducible workflow. For example:
 
 ```shell
-    $ conda create -n pydap_env -c conda-forge python=3.10 pydap-server
+    $ conda create -n pydap_env -c conda-forge python=3.11 pydap-server
     $ conda activate pydap_env
 ```
 
diff --git a/docs/en/requirements.txt b/docs/en/requirements.txt
deleted file mode 100644
index 7e821e4..0000000
--- a/docs/en/requirements.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-jupyter-book
-matplotlib
-numpy
diff --git a/docs/environment.yml b/docs/environment.yml
index 4173be7..198bbb3 100644
--- a/docs/environment.yml
+++ b/docs/environment.yml
@@ -3,7 +3,6 @@ channels:
 - conda-forge
 dependencies:
 - python=3.11
-- pydap-server
 - jupyter-book
 - jupyterlab
 - matplotlib
diff --git a/docs/es/environment.yml b/docs/es/environment.yml
deleted file mode 100644
index 4173be7..0000000
--- a/docs/es/environment.yml
+++ /dev/null
@@ -1,12 +0,0 @@
-name: pydap_docs
-channels:
-- conda-forge
-dependencies:
-- python=3.11
-- pydap-server
-- jupyter-book
-- jupyterlab
-- matplotlib
-- cartopy
-- xarray
-- dask
diff --git a/docs/es/requirements.txt b/docs/es/requirements.txt
deleted file mode 100644
index 7e821e4..0000000
--- a/docs/es/requirements.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-jupyter-book
-matplotlib
-numpy
diff --git a/src/pydap/model.py b/src/pydap/model.py
index 0e16952..6723f14 100644
--- a/src/pydap/model.py
+++ b/src/pydap/model.py
@@ -290,6 +290,17 @@ class BaseType(DapType):
         except AttributeError:
             return self._shape
 
+    @property
+    def dimensions(self):
+        """Return the name of the axes."""
+        warnings.warn(
+            "The use of `dimensions` on a `BaseType` array will get "
+            "deprecated on a future release. Use `dims` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return tuple(self.dims)
+
     def reshape(self, *args):
         """Method that reshapes the data:"""
         self.data = self.data.reshape(*args)
@@ -1065,6 +1076,11 @@ class GridType(StructureType):
         """Return the name of the axes."""
         return tuple(list(self.keys())[1:])
 
+    @property
+    def dims(self):
+        """Return the name of the axes."""
+        return list(self.dimensions)
+
     @property
     def type(self):
         return "Grid"


Test patch:
diff --git a/conftest.py b/conftest.py
index e7a1135..06476f9 100644
--- a/conftest.py
+++ b/conftest.py
@@ -1,3 +1,13 @@
+import os
+
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def set_local_env():
+    os.environ["LOCAL_DEV"] = "1"
+
+
 # Define which file to ignore in tests:
 collect_ignore = ["setup.py", "bootstrap.py", "docs/conf.py"]
 
diff --git a/src/pydap/tests/test_client.py b/src/pydap/tests/test_client.py
index 5082d85..e075e25 100644
--- a/src/pydap/tests/test_client.py
+++ b/src/pydap/tests/test_client.py
@@ -705,6 +705,9 @@ bbox1 = "bounding_box%5B%5D=-10%2C-5%2C10%2C5"
 bbox2 = "bounding_box%5B%5D=-11%2C-6%2C11%2C6"
 
 
+@pytest.mark.skipif(
+    os.getenv("LOCAL_DEV") != "1", reason="This test only runs on local development"
+)
 @pytest.mark.parametrize(
     "param, expected",
     [
diff --git a/src/pydap/tests/test_model.py b/src/pydap/tests/test_model.py
index 7f6677f..6d85973 100644
--- a/src/pydap/tests/test_model.py
+++ b/src/pydap/tests/test_model.py
@@ -89,7 +89,7 @@ def test_BaseType_no_data():
     assert var.dims == []
 
 
-def test_BaseType_data_and_dimensions():
+def test_BaseType_data_and_dims():
     """Test data and dimensions assignment."""
     var = BaseType(
         "var",
@@ -104,6 +104,19 @@ def test_BaseType_data_and_dimensions():
     ]
 
 
+def test_BaseType_raiseWarning_dimensions():
+    """Test data and dimensions assignment."""
+    with pytest.warns(DeprecationWarning, match="`dimensions`"):
+        var = BaseType(
+            "var",
+            [42],
+            [
+                "x",
+            ],
+        )
+        assert var.dimensions == ("x",)
+
+
 def test_BaseType_repr():
     """Test ``__repr__`` method."""
     var = BaseType("var", 42, foo="bar")