Add citations examples, reformat of notebooks, minor fixes

{{cookiecutter.project_name}}/config.py

@@ -1,5 +1,4 @@
-"""
-Contains configuration utils. In its current, default form, configuration will be read from config.json and
+"""Contains configuration utils. In its current, default form, configuration will be read from config.json and
 the git-ignored file config_local.json (you have to create it yourself if you need it) and merged. The config_local.json
 is a good place to keep access keys and other secrets.
 
@@ -39,9 +38,8 @@ class ConfigProvider(ConfigProviderBase[__Configuration]):
 _config_provider = ConfigProvider()
 
 
-def get_config(reload=False) -> __Configuration:
-    """
-    :param reload: if True, the configuration will be reloaded from the json files
+def get_config(reload: bool = False) -> __Configuration:
+    """:param reload: if True, the configuration will be reloaded from the json files
     :return: the configuration instance
     """
     return _config_provider.get_config(reload=reload)

{{cookiecutter.project_name}}/docs/01_tutorials/00_example.rst

@@ -1,3 +1,11 @@
 Example
 =======
-This is a placeholder for the example.
+This is a placeholder for the example.
+
+Citation example
+----------------
+It contains an example of citation :cite:`TURING.1950`.
+
+.. bibliography:: /refs.bib
+    :style: unsrtalpha
+    :filter: docname in docnames

{{cookiecutter.project_name}}/docs/02_notebooks/01_library_example.ipynb

@@ -55,7 +55,7 @@
     "\n",
     "Note that since notebooks are rendered to html+javascript, you can embed interactive components like maps, videos and\n",
     "widgets into your documentation, as long as the interaction does not require re-execution of cells.\n",
-    "Below an example of an interactive map created with plotly"
+    "Below an example of an interactive map created with plotly {cite}`PlotlyMaps`."
    ]
   },
   {
@@ -70,27 +70,38 @@
    "source": [
     "# slightly adjusted example from https://plotly.com/python/mapbox-layers/\n",
     "import pandas as pd\n",
-    "us_cities = pd.read_csv(\"https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv\")\n",
-    "\n",
     "import plotly.express as px\n",
     "\n",
-    "fig = px.scatter_mapbox(us_cities, lat=\"lat\", lon=\"lon\", hover_name=\"City\", hover_data=[\"State\", \"Population\"],\n",
-    "                        color_discrete_sequence=[\"fuchsia\"], zoom=3, height=300)\n",
-    "fig.update_layout(mapbox_style=\"open-street-map\")\n",
-    "fig.update_layout(margin={\"r\":0,\"t\":0,\"l\":0,\"b\":0})\n",
+    "us_cities = pd.read_csv(\n",
+    "    \"https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv\",\n",
+    ")\n",
+    "\n",
+    "fig = px.scatter_mapbox(\n",
+    "    us_cities,\n",
+    "    lat=\"lat\",\n",
+    "    lon=\"lon\",\n",
+    "    hover_name=\"City\",\n",
+    "    hover_data=[\"State\", \"Population\"],\n",
+    "    color_discrete_sequence=[\"fuchsia\"],\n",
+    "    zoom=3,\n",
+    "    height=300,\n",
+    ")\n",
+    "\n",
+    "fig.update_layout(mapbox_style=\"open-street-map\", margin={\"r\": 0, \"t\": 0, \"l\": 0, \"b\": 0})\n",
     "fig.show()"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
+   "source": [
+    "```{bibliography}\n",
+    ":style: unsrtalpha\n",
+    ":filter: docname in docnames\n",
+    "```"
+   ],
    "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
-   "outputs": [],
-   "source": []
+    "collapsed": false
+   }
   }
  ],
  "metadata": {

{{cookiecutter.project_name}}/docs/02_notebooks/02_config_example.ipynb

@@ -29,12 +29,13 @@
     "%load_ext autoreload\n",
     "%autoreload 2\n",
     "\n",
-    "import sys, os\n",
+    "import os\n",
+    "import sys\n",
     "\n",
     "# in order to get the config (it is not part of the library) and sane paths to data\n",
     "if os.path.basename(os.getcwd()) != \"02_notebooks\":\n",
-    "    raise Exception(f\"Wrong directory. Did you execute this cell twice?\")\n",
-    "os.chdir(\"..\")\n",
+    "    raise Exception(\"Wrong directory. Did you execute this cell twice?\")\n",
+    "os.chdir(\"../..\")\n",
     "sys.path.append(os.path.abspath(\".\"))"
    ]
   },
@@ -50,7 +51,7 @@
    "source": [
     "from config import get_config\n",
     "\n",
-    "c  = get_config(reload=True)"
+    "c = get_config(reload=True)"
    ]
   },
   {

{{cookiecutter.project_name}}/docs/autogen_rst.py

@@ -2,7 +2,6 @@
 import os
 import shutil
 from pathlib import Path
-from typing import Optional
 
 log = logging.getLogger(os.path.basename(__file__))
 
@@ -19,7 +18,7 @@ def module_template(module_qualname: str):
 """
 
 
-def index_template(package_name: str, doc_references: Optional[list[str]] = None, text_prefix=""):
+def index_template(package_name: str, doc_references: list[str] | None = None, text_prefix=""):
     doc_references = doc_references or ""
     if doc_references:
         doc_references = "\n" + "\n".join(f"* :doc:`{ref}`" for ref in doc_references) + "\n"

{{cookiecutter.project_name}}/docs/bibtex.json

@@ -0,0 +1,10 @@
+{
+    "cited": {
+        "01_tutorials/00_example": [
+            "TURING.1950"
+        ],
+        "02_notebooks/00_example": [
+            "PlotlyMaps"
+        ]
+    }
+}

{{cookiecutter.project_name}}/docs/refs.bib

@@ -0,0 +1,21 @@
+@article{TURING.1950,
+ author = {TURING, A. M.},
+ year = {1950},
+ title = {I.---COMPUTING MACHINERY AND INTELLIGENCE},
+ pages = {433--460},
+ volume = {LIX},
+ number = {236},
+ issn = {0026-4423},
+ journal = {Mind},
+ doi = {10.1093/mind/LIX.236.433},
+ file = {ICOMPUTING MACHINERY AND INTELLIGENCE:Attachments/ICOMPUTING MACHINERY AND INTELLIGENCE.pdf:application/pdf}
+}
+
+
+@misc{PlotlyMaps,
+ abstract = {Plotly's},
+ year = {2/16/2024},
+ title = {Maps},
+ url = {https://plotly.com/python/maps/},
+ urldate = {2/28/2024}
+}

{{cookiecutter.project_name}}/docs/spelling_wordlist.txt

@@ -1,3 +1,20 @@
 {{cookiecutter.project_name}}
 {{cookiecutter.package_name}}
 {{cookiecutter.author}}
+
+appliedAI
+autogenerated
+colab
+docstring
+docstrings
+Github
+html
+init
+javascript
+pre
+pycharm
+pydocstyle
+submodules
+subpackages
+utils
+webpage

{{cookiecutter.project_name}}/src/{{cookiecutter.project_name}}/sample_module.py

@@ -1,11 +1,8 @@
-"""
-Top-level module
-"""
+"""Top-level module."""
 
 
 class SampleClass:
-    """
-    Sample docstring. Note that init docstrings should be underneath the class and not the init method itself
+    """Sample docstring. Note that init docstrings should be underneath the class and not the init method itself
     (this looks prettier in sphinx). They still will be rendered correctly in pycharm's quick documentation.
 
     :param param: some parameter
@@ -16,12 +13,11 @@ def __init__(self, param: str | None = None):
         self.param = param
 
     def sample_method(self, name: str) -> str:
-        """
-        >>> from {{cookiecutter.project_name}}.sample_module import SampleClass
+        """>>> from {{cookiecutter.project_name}}.sample_module import SampleClass
         >>>
         >>> greeter = SampleClass()
         >>> greeter.sample_method("{{cookiecutter.author}}")
-        'hello {{cookiecutter.author}}'
+        'hello {{cookiecutter.author}}'.
 
         :param name:
         :return:

{{cookiecutter.project_name}}/src/{{cookiecutter.project_name}}/sample_package/sample_module.py

@@ -1,10 +1,6 @@
-"""
-Module in a separate package
-"""
+"""Module in a separate package."""
 
 
 def hello_stranger() -> None:
-    """
-    hello
-    """
+    """Hello."""
     print("Hello from a separate package!")