Propagate original description to foreign variables (#91)

* Decouple autodoc from foreign variable description

When looking up the description of a foreign variable, its original
description will be returned, independently of the autodoc feature
integration.

* Passed black and flake8

* Updated doc/whats_new.rst

* Directly access metadata description

* Added test for xsimlab.foreign, minor modifications

* Passed black and flake8

* Refine testing

To restrict the scope of testing as well as preserving consistency
between `xsimlab.foreign` and pytest logic, description is accessed
directly via `attr.fields_dict` in `xsimlab.foreign` and `attr.fields`
in the test procedure.

doc/whats_new.rst

@@ -49,6 +49,8 @@ Enhancements
   extension (:issue:`85`).
 - %-formatting and str.format() code has been converted into formatted string
   literals (f-strings) (:issue:`90`).
+- :func:`~xsimlab.foreign` has been updated to get the original description
+  of a foreign variable (:issue:`91`)
 
 Bug fixes
 ~~~~~~~~~

xsimlab/tests/fixture_process.py

@@ -23,7 +23,7 @@ def compute_some_od_var(self):
 class AnotherProcess:
     """Just used for foreign variables in ExampleProcess."""
 
-    another_var = xs.variable()
+    another_var = xs.variable(description="original description")
     some_var = xs.foreign(SomeProcess, "some_var")
 
 

xsimlab/tests/test_variable.py

@@ -1,6 +1,7 @@
 import pytest
+import attr
 
-from xsimlab.tests.fixture_process import ExampleProcess
+from xsimlab.tests.fixture_process import AnotherProcess, ExampleProcess
 from xsimlab.variable import _as_dim_tuple, _as_group_tuple, foreign
 
 
@@ -54,5 +55,8 @@ def test_as_group_tuple(groups, group, expected):
 def test_foreign():
     with pytest.raises(ValueError) as excinfo:
         foreign(ExampleProcess, "some_var", intent="inout")
-
     assert "intent='inout' is not supported" in str(excinfo.value)
+
+    actual = attr.fields(ExampleProcess).out_foreign_var.metadata["description"]
+    expected = attr.fields(AnotherProcess).another_var.metadata["description"]
+    assert actual == expected

xsimlab/variable.py

@@ -285,10 +285,7 @@ def foreign(other_process_cls, var_name, intent="in"):
     if intent == "inout":
         raise ValueError("intent='inout' is not supported for foreign variables")
 
-    description = (
-        f"Reference to variable {var_name!r} defined "
-        f"in class {other_process_cls.__name__!r}"
-    )
+    description = attr.fields_dict(other_process_cls)[var_name].metadata["description"]
 
     metadata = {
         "var_type": VarType.FOREIGN,