Initial commit from pymetrius template

docs/.gitignore

@@ -0,0 +1,5 @@
+/03_api/*
+jupyter_execute
+_toc.yml
+.jupyter_cache
+conf.py

docs/01_tutorials/00_example.rst

@@ -0,0 +1,11 @@
+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

docs/01_tutorials/index.rst

@@ -0,0 +1,2 @@
+Tutorials
+=========

docs/02_notebooks/00_intro.md

@@ -0,0 +1,4 @@
+# Notebook Tutorials
+
+Here is a collection of executable tutorials for serena. 
+You can run them directly in colab, or download them and run them locally.

docs/02_notebooks/01_library_example.ipynb

@@ -0,0 +1,128 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# The role of notebooks\n",
+    "\n",
+    "Notebooks are great for illustrations and examples that at the same time serve as integration tests.\n",
+    "In this library template, notebooks will be executed with pytest (thus on every\n",
+    "commit in your CI/CD pipeline). The results of the executions will be saved to the docs directory and converted to\n",
+    "static websites through nbconvert. The static websites are then added to the documentation under the\n",
+    "_Guides and Tutorials_ section. These websites will be deployed to Github pages on push to develop."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Before running the notebook\n",
+    "\n",
+    "Install the library and its dependencies with, if you haven't done so already\n",
+    "```\n",
+    "poetry install\n",
+    "```\n",
+    "from the root directory. You can also execute this command directly in the notebook but will need to reload the\n",
+    "kernel afterwards"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# Here an illustration of your library\n",
+    "from serena.sample_package.sample_module import hello_stranger\n",
+    "\n",
+    "hello_stranger()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "## Interactive Documentation\n",
+    "\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 {cite}`PlotlyMaps`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# slightly adjusted example from https://plotly.com/python/mapbox-layers/\n",
+    "import pandas as pd\n",
+    "import plotly.express as px\n",
+    "\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": "markdown",
+   "source": [
+    "```{bibliography}\n",
+    ":style: unsrtalpha\n",
+    ":filter: docname in docnames\n",
+    "```"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

docs/04_contributing/04_contributing.rst

@@ -0,0 +1,91 @@
+Contributing to serena
+=============================================
+
+
+Install Develop Version
+-----------------------
+
+serena is built and managed by `poetry <https://python-poetry.org/>`_. For example,
+to install all relevant requirements in editable mode you can simply call
+
+.. code-block:: bash
+
+  $ poetry install --with dev
+
+
+PEP8 Code Style Check and Formatting
+----------------------------------------
+
+Please set up pre-commit by running
+
+.. code-block:: bash
+
+    $ pre-commit install
+
+in the main directory. This should make sure that your contribution is properly
+formatted before every commit.
+
+The code is inspected and formatted by `black` and `ruff`. They are executed as
+pre-commit hooks. In addition, `poe the poet` tasks are configured.
+Simply run `poe` to see the available tasks.
+E.g, to format and check the linting manually you can run:
+
+.. code-block:: bash
+
+    $ poe format
+    $ poe lint
+
+
+Type Check
+----------
+
+We use `mypy <https://github.com/python/mypy/>`_ to check the type annotations. To check, in the main directory, run:
+
+.. code-block:: bash
+
+    $ poe type-check
+
+
+Test Locally
+------------
+
+This command will run automatic tests in the main directory
+
+.. code-block:: bash
+
+    $ poe test
+
+
+Documentation
+-------------
+
+Documentations are written under the ``docs/`` directory as ReStructuredText (``.rst``) files. ``index.rst`` is the main page. A Tutorial on ReStructuredText can be found `here <https://pythonhosted.org/an_example_pypi_project/sphinx.html>`_.
+
+API References are automatically generated by `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ according to the outlines under ``docs/api/`` and should be modified when any code changes.
+
+To compile documentation into webpage, run
+
+.. code-block:: bash
+
+    $ poe doc-build
+
+The generated webpage is in ``docs/_build`` and can be viewed with browser (http://0.0.0.0:8000/).
+
+
+Documentation Generation Test
+-----------------------------
+
+We have the following three documentation tests:
+
+1. pydocstyle (as part of ruff): test all docstrings;
+
+2. doc8 (as part of ruff): test ReStructuredText format;
+
+3. sphinx spelling and test: test if there is any error/warning when generating front-end html documentation.
+
+To check, in the main directory, run:
+
+.. code-block:: bash
+
+    $ poe lint
+    $ poe doc-build

docs/_config.yml

@@ -0,0 +1,147 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# Users are expected to override these values in their own `_config.yml` file.
+# This is also the "master list" of all allowed keys and values.
+
+#######################################################################################
+# Book settings
+title                       : serena Documentation  # The title of the book. Will be placed in the left navbar.
+author                      : serena contributors  # The author of the book
+copyright                   : ""  # Copyright year to be placed in the footer
+logo                        : "" # A path to the book logo
+# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
+exclude_patterns            : ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build', 'jupyter_execute', '.jupyter_cache', '.pytest_cache', 'docs/autogen_rst.py', 'docs/create_toc.py']
+# Auto-exclude files not in the toc
+only_build_toc_files        : false
+
+#######################################################################################
+# Execution settings
+execute:
+  execute_notebooks         : cache  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
+  cache                     : ""    # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/`
+  exclude_patterns          : []    # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time)
+  timeout                   : -1    # The maximum time (in seconds) each notebook cell is allowed to run.
+  run_in_temp               : false # If `True`, then a temporary directory will be created and used as the command working directory (cwd),
+                                    # otherwise the notebook's parent directory will be the cwd.
+  allow_errors              : false # If `False`, when a code cell raises an error the execution is stopped, otherwise all cells are always run.
+  stderr_output             : show  # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe'
+
+#######################################################################################
+# Parse and render settings
+parse:
+  myst_enable_extensions: # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    - amsmath
+    - colon_fence
+    # - deflist
+    - dollarmath
+    # - html_admonition
+    # - html_image
+    - linkify
+    # - replacements
+    # - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [ mailto, http, https ] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context
+
+#######################################################################################
+# HTML-specific settings
+html:
+  favicon                   : ""  # A path to a favicon image
+  use_edit_page_button      : false  # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in
+  use_repository_button     : false  # Whether to add a link to your repository button
+  use_issues_button         : false  # Whether to add an "open an issue" button
+  use_multitoc_numbering    : true   # Continuous numbering across parts/chapters
+  extra_footer              : ""
+  google_analytics_id       : ""  # A GA id that can be used to track book views.
+  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
+  baseurl                   : "https://github.com/oraios/serena"
+  analytics:
+
+  comments:
+    hypothesis              : false
+    utterances              : false
+  announcement              : "" # A banner announcement at the top of the site.
+
+#######################################################################################
+# LaTeX-specific settings
+latex:
+  latex_engine              : pdflatex  # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex     : true # use sphinx-jupyterbook-latex for pdf builds as default
+  targetname                : book.tex
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - refs.bib
+
+#######################################################################################
+# Launch button settings
+launch_buttons:
+  notebook_interface        : classic  # The interface interactive links will activate ["classic", "jupyterlab"]
+  binderhub_url             : ""  # The URL of the BinderHub (e.g., https://mybinder.org)
+  jupyterhub_url            : ""  # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu)
+  thebe                     : false  # Add a thebe button to pages (requires the repository to run on Binder)
+  colab_url                 : "https://colab.research.google.com"
+
+repository:
+  url                       : https://github.com/oraios/serena  # The URL to your book's repository
+  path_to_book              : docs  # A path to your book's folder, relative to the repository root.
+  branch                    : main  # Which branch of the repository should be used when creating links
+
+#######################################################################################
+# Advanced and power-user settings
+sphinx:
+  extra_extensions          :
+    - sphinx.ext.autodoc
+    - sphinx.ext.viewcode
+    - sphinx_toolbox.more_autodoc.sourcelink
+    - sphinxcontrib.spelling
+  local_extensions          :   # A list of local extensions to load by sphinx specified by "name: path" items
+  recursive_update          : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false)
+  config                    :   # key-value pairs to directly over-ride the Sphinx configuration
+    autodoc_typehints_format: "short"
+    autodoc_member_order: "bysource"
+    autoclass_content: "both"
+    autodoc_default_options:
+      show-inheritance: True
+    suppress_warnings: ["mystnb.unknown_mime_type"]  # needed for plotly rendering
+    autodoc_show_sourcelink: True
+    add_module_names: False
+    github_username: oraios
+    github_repository: https://github.com/oraios/serena
+    python_use_unqualified_type_names: True
+    nb_mime_priority_overrides: [
+      [ 'html', 'application/vnd.jupyter.widget-view+json', 10 ],
+      [ 'html', 'application/javascript', 20 ],
+      [ 'html', 'text/html', 30 ],
+      [ 'html', 'text/latex', 40 ],
+      [ 'html', 'image/svg+xml', 50 ],
+      [ 'html', 'image/png', 60 ],
+      [ 'html', 'image/jpeg', 70 ],
+      [ 'html', 'text/markdown', 80 ],
+      [ 'html', 'text/plain', 90 ],
+      [ 'spelling', 'application/vnd.jupyter.widget-view+json', 10 ],
+      [ 'spelling', 'application/javascript', 20 ],
+      [ 'spelling', 'text/html', 30 ],
+      [ 'spelling', 'text/latex', 40 ],
+      [ 'spelling', 'image/svg+xml', 50 ],
+      [ 'spelling', 'image/png', 60 ],
+      [ 'spelling', 'image/jpeg', 70 ],
+      [ 'spelling', 'text/markdown', 80 ],
+      [ 'spelling', 'text/plain', 90 ],
+    ]
+    mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+    mathjax3_config:
+      loader: { load: [ '[tex]/configmacros' ] }
+      tex:
+        packages: { '[+]': [ 'configmacros' ] }
+        macros:
+          vect: ["{\\mathbf{\\boldsymbol{#1}} }", 1]
+          E: "{\\mathbb{E}}"
+          P: "{\\mathbb{P}}"
+          R: "{\\mathbb{R}}"
+          abs: ["{\\left| #1 \\right|}", 1]
+          simpl: ["{\\Delta^{#1} }", 1]
+          amax: "{\\text{argmax}}"

docs/_static/css/style.css

@@ -0,0 +1,138 @@
+body {
+    font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
+}
+
+/* Default header fonts are ugly */
+h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend, p.caption {
+    font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
+}
+
+/* Use white for docs background */
+.wy-side-nav-search {
+    background-color: #fff;
+}
+
+.wy-nav-content {
+    max-width: 1200px !important;
+}
+
+.wy-nav-content-wrap, .wy-menu li.current > a  {
+    background-color: #fff;
+}
+
+.wy-side-nav-search>a img.logo {
+    width: 80%;
+    margin-top: 10px;
+}
+
+@media screen and (min-width: 1400px) {
+    .wy-nav-content-wrap {
+        background-color: #fff;
+    }
+
+    .wy-nav-content {
+        background-color: #fff;
+    }
+}
+
+/* Fixes for mobile */
+.wy-nav-top {
+    background-color: #fff;
+    background-repeat: no-repeat;
+    background-position: center;
+    padding: 0;
+    margin: 0.4045em 0.809em;
+    color: #333;
+}
+
+.wy-nav-top > a {
+    display: none;
+}
+
+@media screen and (max-width: 768px) {
+    .wy-side-nav-search>a img.logo {
+        height: 60px;
+    }
+}
+
+/* This is needed to ensure that logo above search scales properly */
+.wy-side-nav-search a {
+    display: block;
+}
+
+/* This ensures that multiple constructors will remain in separate lines. */
+.rst-content dl:not(.docutils) dt {
+    display: table;
+}
+
+/* Use our red for literals (it's very similar to the original color) */
+.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
+    color: #4692BC;
+}
+
+.rst-content tt.xref, a .rst-content tt, .rst-content tt.xref,
+.rst-content code.xref, a .rst-content tt, a .rst-content code {
+    color: #404040;
+}
+
+/* Change link colors (except for the menu) */
+
+a {
+    color: #4692BC;
+}
+
+a:hover {
+    color: #4692BC;
+}
+
+
+a:visited {
+    color: #4692BC;
+}
+
+.wy-menu a {
+    color: #b3b3b3;
+}
+
+.wy-menu a:hover {
+    color: #b3b3b3;
+}
+
+/* Default footer text is quite big */
+footer {
+    font-size: 80%;
+}
+
+footer .rst-footer-buttons {
+    font-size: 125%; /* revert footer settings - 1/80% = 125% */
+}
+
+footer p {
+    font-size: 100%;
+}
+
+.ethical-rtd {
+    display: none;
+}
+
+.ethical-fixedfooter {
+    display: none;
+}
+
+.ethical-content {
+    display: none;
+}
+
+/* For hidden headers that appear in TOC tree */
+/* see http://stackoverflow.com/a/32363545/3343043 */
+.rst-content .hidden-section {
+    display: none;
+}
+
+nav .hidden-section {
+    display: inherit;
+}
+
+.wy-side-nav-search>div.version {
+    color: #000;
+}

docs/_static/js/require.min.js

@@ -0,0 +1,5 @@
+/** vim: et:ts=4:sw=4:sts=4
+ * @license RequireJS 2.3.6 Copyright jQuery Foundation and other contributors.
+ * Released under MIT license, https://github.com/requirejs/requirejs/blob/master/LICENSE
+ */
+var requirejs,require,define;!function(global,setTimeout){var req,s,head,baseElement,dataMain,src,interactiveScript,currentlyAddingScript,mainScript,subPath,version="2.3.6",commentRegExp=/\/\*[\s\S]*?\*\/|([^:"'=]|^)\/\/.*$/gm,cjsRequireRegExp=/[^.]\s*require\s*\(\s*["']([^'"\s]+)["']\s*\)/g,jsSuffixRegExp=/\.js$/,currDirRegExp=/^\.\//,op=Object.prototype,ostring=op.toString,hasOwn=op.hasOwnProperty,isBrowser=!("undefined"==typeof window||"undefined"==typeof navigator||!window.document),isWebWorker=!isBrowser&&"undefined"!=typeof importScripts,readyRegExp=isBrowser&&"PLAYSTATION 3"===navigator.platform?/^complete$/:/^(complete|loaded)$/,defContextName="_",isOpera="undefined"!=typeof opera&&"[object Opera]"===opera.toString(),contexts={},cfg={},globalDefQueue=[],useInteractive=!1;function commentReplace(e,t){return t||""}function isFunction(e){return"[object Function]"===ostring.call(e)}function isArray(e){return"[object Array]"===ostring.call(e)}function each(e,t){var i;if(e)for(i=0;i<e.length&&(!e[i]||!t(e[i],i,e));i+=1);}function eachReverse(e,t){var i;if(e)for(i=e.length-1;-1<i&&(!e[i]||!t(e[i],i,e));i-=1);}function hasProp(e,t){return hasOwn.call(e,t)}function getOwn(e,t){return hasProp(e,t)&&e[t]}function eachProp(e,t){var i;for(i in e)if(hasProp(e,i)&&t(e[i],i))break}function mixin(i,e,r,n){return e&&eachProp(e,function(e,t){!r&&hasProp(i,t)||(!n||"object"!=typeof e||!e||isArray(e)||isFunction(e)||e instanceof RegExp?i[t]=e:(i[t]||(i[t]={}),mixin(i[t],e,r,n)))}),i}function bind(e,t){return function(){return t.apply(e,arguments)}}function scripts(){return document.getElementsByTagName("script")}function defaultOnError(e){throw e}function getGlobal(e){if(!e)return e;var t=global;return each(e.split("."),function(e){t=t[e]}),t}function makeError(e,t,i,r){var n=new Error(t+"\nhttps://requirejs.org/docs/errors.html#"+e);return n.requireType=e,n.requireModules=r,i&&(n.originalError=i),n}if(void 0===define){if(void 0!==requirejs){if(isFunction(requirejs))return;cfg=requirejs,requirejs=void 0}void 0===require||isFunction(require)||(cfg=require,require=void 0),req=requirejs=function(e,t,i,r){var n,o,a=defContextName;return isArray(e)||"string"==typeof e||(o=e,isArray(t)?(e=t,t=i,i=r):e=[]),o&&o.context&&(a=o.context),(n=getOwn(contexts,a))||(n=contexts[a]=req.s.newContext(a)),o&&n.configure(o),n.require(e,t,i)},req.config=function(e){return req(e)},req.nextTick=void 0!==setTimeout?function(e){setTimeout(e,4)}:function(e){e()},require||(require=req),req.version=version,req.jsExtRegExp=/^\/|:|\?|\.js$/,req.isBrowser=isBrowser,s=req.s={contexts:contexts,newContext:newContext},req({}),each(["toUrl","undef","defined","specified"],function(t){req[t]=function(){var e=contexts[defContextName];return e.require[t].apply(e,arguments)}}),isBrowser&&(head=s.head=document.getElementsByTagName("head")[0],baseElement=document.getElementsByTagName("base")[0],baseElement&&(head=s.head=baseElement.parentNode)),req.onError=defaultOnError,req.createNode=function(e,t,i){var r=e.xhtml?document.createElementNS("http://www.w3.org/1999/xhtml","html:script"):document.createElement("script");return r.type=e.scriptType||"text/javascript",r.charset="utf-8",r.async=!0,r},req.load=function(t,i,r){var e,n=t&&t.config||{};if(isBrowser)return(e=req.createNode(n,i,r)).setAttribute("data-requirecontext",t.contextName),e.setAttribute("data-requiremodule",i),!e.attachEvent||e.attachEvent.toString&&e.attachEvent.toString().indexOf("[native code")<0||isOpera?(e.addEventListener("load",t.onScriptLoad,!1),e.addEventListener("error",t.onScriptError,!1)):(useInteractive=!0,e.attachEvent("onreadystatechange",t.onScriptLoad)),e.src=r,n.onNodeCreated&&n.onNodeCreated(e,n,i,r),currentlyAddingScript=e,baseElement?head.insertBefore(e,baseElement):head.appendChild(e),currentlyAddingScript=null,e;if(isWebWorker)try{setTimeout(function(){},0),importScripts(r),t.completeLoad(i)}catch(e){t.onError(makeError("importscripts","importScripts failed for "+i+" at "+r,e,[i]))}},isBrowser&&!cfg.skipDataMain&&eachReverse(scripts(),function(e){if(head||(head=e.parentNode),dataMain=e.getAttribute("data-main"))return mainScript=dataMain,cfg.baseUrl||-1!==mainScript.indexOf("!")||(mainScript=(src=mainScript.split("/")).pop(),subPath=src.length?src.join("/")+"/":"./",cfg.baseUrl=subPath),mainScript=mainScript.replace(jsSuffixRegExp,""),req.jsExtRegExp.test(mainScript)&&(mainScript=dataMain),cfg.deps=cfg.deps?cfg.deps.concat(mainScript):[mainScript],!0}),define=function(e,i,t){var r,n;"string"!=typeof e&&(t=i,i=e,e=null),isArray(i)||(t=i,i=null),!i&&isFunction(t)&&(i=[],t.length&&(t.toString().replace(commentRegExp,commentReplace).replace(cjsRequireRegExp,function(e,t){i.push(t)}),i=(1===t.length?["require"]:["require","exports","module"]).concat(i))),useInteractive&&(r=currentlyAddingScript||getInteractiveScript())&&(e||(e=r.getAttribute("data-requiremodule")),n=contexts[r.getAttribute("data-requirecontext")]),n?(n.defQueue.push([e,i,t]),n.defQueueMap[e]=!0):globalDefQueue.pushLine truncated

docs/autogen_rst.py

@@ -0,0 +1,141 @@
+import logging
+import os
+import shutil
+from pathlib import Path
+
+log = logging.getLogger(os.path.basename(__file__))
+
+
+def module_template(module_qualname: str):
+    module_name = module_qualname.split(".")[-1]
+    title = module_name.replace("_", r"\_")
+    return f"""{title}
+{"=" * len(title)}
+
+.. automodule:: {module_qualname}
+   :members:
+   :undoc-members:
+"""
+
+
+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"
+
+    dirname = package_name.split(".")[-1]
+    title = dirname.replace("_", r"\_")
+    if title == "serena":
+        title = "serena API Reference"
+    return f"{title}\n{'=' * len(title)}" + text_prefix + doc_references
+
+
+def write_to_file(content: str, path: str):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        f.write(content)
+    os.chmod(path, 0o666)
+
+
+_SUBTITLE = (
+    "\n Here is the autogenerated documentation of the serena API. \n \n "
+    "The Table of Contents to the left has the same structure as the "
+    "repository's package code. The links at each page point to the submodules and subpackages. \n\n "
+    "Enjoy scrolling through! \n"
+)
+
+
+def make_rst(src_root, rst_root, clean=False, overwrite=False, package_prefix=""):
+    """Creates/updates documentation in form of rst files for modules and packages.
+
+    Does not delete any existing rst files. Thus, rst files for packages or modules that have been removed or renamed
+    should be deleted by hand.
+
+    This method should be executed from the project's top-level directory
+
+    :param src_root: path to library base directory, typically "src/<library_name>"
+    :param clean: whether to completely clean the target directory beforehand, removing any existing .rst files
+    :param overwrite: whether to overwrite existing rst files. This should be used with caution as it will delete
+        all manual changes to documentation files
+    :package_prefix: a prefix to prepend to each module (for the case where the src_root is not the base package),
+        which, if not empty, should end with a "."
+    :return:
+    """
+    rst_root = os.path.abspath(rst_root)
+
+    if clean and os.path.isdir(rst_root):
+        shutil.rmtree(rst_root)
+
+    base_package_name = package_prefix + os.path.basename(src_root)
+
+    # TODO: reduce duplication with same logic for subpackages below
+    files_in_dir = os.listdir(src_root)
+    module_names = [f[:-3] for f in files_in_dir if f.endswith(".py") and not f.startswith("_")]
+    subdir_refs = [f"{f}/index" for f in files_in_dir if os.path.isdir(os.path.join(src_root, f)) and not f.startswith("_")]
+    package_index_rst_path = os.path.join(
+        rst_root,
+        "index.rst",
+    )
+    log.info(f"Writing {package_index_rst_path}")
+    write_to_file(
+        index_template(
+            base_package_name,
+            doc_references=module_names + subdir_refs,
+            text_prefix=_SUBTITLE,
+        ),
+        package_index_rst_path,
+    )
+
+    for root, dirnames, filenames in os.walk(src_root):
+        if os.path.basename(root).startswith("_"):
+            continue
+        base_package_relpath = os.path.relpath(root, start=src_root)
+        base_package_qualname = package_prefix + os.path.relpath(
+            root,
+            start=os.path.dirname(src_root),
+        ).replace(os.path.sep, ".")
+
+        for dirname in dirnames:
+            if dirname.startswith("_"):
+                log.debug(f"Skipping {dirname}")
+                continue
+            files_in_dir = os.listdir(os.path.join(root, dirname))
+            module_names = [f[:-3] for f in files_in_dir if f.endswith(".py") and not f.startswith("_")]
+            subdir_refs = [f"{f}/index" for f in files_in_dir if os.path.isdir(os.path.join(root, dirname, f)) and not f.startswith("_")]
+            if not module_names:
+                log.debug(f"Skipping {dirname} as it does not contain any .py files")
+                continue
+            package_qualname = f"{base_package_qualname}.{dirname}"
+            package_index_rst_path = os.path.join(
+                rst_root,
+                base_package_relpath,
+                dirname,
+                "index.rst",
+            )
+            log.info(f"Writing {package_index_rst_path}")
+            write_to_file(
+                index_template(package_qualname, doc_references=module_names + subdir_refs),
+                package_index_rst_path,
+            )
+
+        for filename in filenames:
+            base_name, ext = os.path.splitext(filename)
+            if ext == ".py" and not filename.startswith("_"):
+                module_qualname = f"{base_package_qualname}.{filename[:-3]}"
+
+                module_rst_path = os.path.join(rst_root, base_package_relpath, f"{base_name}.rst")
+                if os.path.exists(module_rst_path) and not overwrite:
+                    log.debug(f"{module_rst_path} already exists, skipping it")
+
+                log.info(f"Writing module documentation to {module_rst_path}")
+                write_to_file(module_template(module_qualname), module_rst_path)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    docs_root = Path(__file__).parent
+    make_rst(
+        docs_root / ".." / "src" / "serena",
+        docs_root / "03_api",
+        clean=True,
+    )

docs/bibtex.json

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

docs/create_toc.py

@@ -0,0 +1,8 @@
+import os
+from pathlib import Path
+
+# This script provides a platform-independent way of making the jupyter-book call (used in pyproject.toml)
+toc_file = Path(__file__).parent / "_toc.yml"
+cmd = f"jupyter-book toc from-project docs -e .rst -e .md -e .ipynb  >{toc_file}"
+print(cmd)
+os.system(cmd)

docs/index.rst

@@ -0,0 +1,15 @@
+Welcome to serena!
+=========================================
+
+Welcome to the serena library.
+See the project's repository_  for more information.
+
+.. _repository: https://github.com/oraios/serena
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/nbstripout.py

@@ -0,0 +1,11 @@
+"""Implements a platform-independent way of calling nbstripout (used in pyproject.toml)."""
+
+import glob
+import os
+from pathlib import Path
+
+if __name__ == "__main__":
+    docs_dir = Path(__file__).parent
+    for path in glob.glob(str(docs_dir / "02_notebooks" / "*.ipynb")):
+        cmd = f"nbstripout {path}"
+        os.system(cmd)

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}
+}

docs/spelling_wordlist.txt

@@ -0,0 +1,21 @@
+serena
+serena
+Oraios AI
+oraios
+
+appliedAI
+autogenerated
+colab
+docstring
+docstrings
+Github
+html
+init
+javascript
+pre
+pycharm
+pydocstyle
+submodules
+subpackages
+utils
+webpage