tiennm99/serena
1
0 Fork 0
mirror of https://github.com/tiennm99/serena.git synced 2026-10-13 06:15:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove ./docs and docs-related dependencies/tools

Browse Source
This commit is contained in:
Dominik Jain committed 2025-04-01 00:36:27 +02:00
1 parent 6b05025209
commit f1ac3faf0c
17 files changed
-782
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/.gitignore
-5
View File
@@ -1,5 +0,0 @@
/03_api/*
jupyter_execute
_toc.yml
.jupyter_cache
conf.py
docs/01_tutorials/00_example.rst
-11
View File
@@ -1,11 +0,0 @@
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
-2
View File
@@ -1,2 +0,0 @@
Tutorials
=========
docs/02_notebooks/00_intro.md
-4
View File
@@ -1,4 +0,0 @@
# 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
-128
View File
@@ -1,128 +0,0 @@
{
"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
-91
View File
@@ -1,91 +0,0 @@
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
-147
View File
@@ -1,147 +0,0 @@
# 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
Vendored
-138
View File
@@ -1,138 +0,0 @@
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
Vendored
-5
View File
@@ -1,5 +0,0 @@
/** 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
-141
View File
@@ -1,141 +0,0 @@
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
-10
View File
@@ -1,10 +0,0 @@
{
"cited": {
"01_tutorials/00_example": [
"TURING.1950"
],
"02_notebooks/00_example": [
"PlotlyMaps"
]
}
}
docs/create_toc.py
-8
View File
@@ -1,8 +0,0 @@
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
-15
View File
@@ -1,15 +0,0 @@
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
-11
View File
@@ -1,11 +0,0 @@
"""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
-21
View File
@@ -1,21 +0,0 @@
@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
-21
View File
@@ -1,21 +0,0 @@
serena
serena
Oraios AI
oraios
appliedAI
autogenerated
colab
docstring
docstrings
Github
html
init
javascript
pre
pycharm
pydocstyle
submodules
subpackages
utils
webpage
pyproject.toml
-24
View File
@@ -41,29 +41,15 @@ text = "MIT"
[project.optional-dependencies]
dev = [
"black[jupyter]>=23.7.0",
"docutils>=0.20.1",
"jinja2",
"jupyter>=1.0.0",
# In version 1.0.4 we get a NoneType error related to some config conversion (yml_analytics is None and should be a list)
"jupyter-book==1.0.0",
"mypy>=1.4.1",
"nbqa>=1.7.1",
"nbstripout>=0.6.1",
"poethepoet>=0.20.0",
"pre-commit>=3.3.3",
"pytest>=8.0.2",
"pytest-cov",
"ruff>=0.0.285",
"sphinx>=7",
"sphinx-book-theme>=1.0.1",
"sphinx-comments>=0.0.3",
"sphinx-copybutton>=0.5.2",
"sphinx-jupyterbook-latex>=1.0.0",
"toml-sort>=0.24.2",
"sphinx-togglebutton>=0.3.2",
"sphinx-toolbox>=3.5.0",
"sphinxcontrib-bibtex",
"sphinxcontrib-spelling>=8.0.0",
"types-pyyaml>=6.0.12.20241230",
]
agno = [
@@ -109,10 +95,6 @@ warn_unused_configs = true
warn_unused_ignores = true
exclude = "^build/|^docs/"
[tool.nbqa.exclude]
ruff = "\\.jupyter_cache|jupyter_execute"
mypy = "\\.jupyter_cache|jupyter_execute"
[tool.poe.env]
PYDEVD_DISABLE_FILE_VALIDATION = "1"
@@ -120,19 +102,15 @@ PYDEVD_DISABLE_FILE_VALIDATION = "1"
test = "pytest test --cov=serena --cov-report=xml --cov-report=term-missing --durations=0 -v --color=yes"
_black_check = "black --check --exclude src/multilspy/ src scripts test"
_ruff_check = "ruff check --exclude .venv/ --exclude src/multilspy/ src scripts test"
_ruff_check_nb = "nbqa ruff check docs"
_black_format = "black --exclude .venv/|src/multilspy/ src scripts test"
_ruff_format = "ruff check --exclude src/multilspy/ --fix src scripts test"
_ruff_format_nb = "nbqa ruff --fix docs"
lint = [
"_black_check",
"_ruff_check",
#"_ruff_check_nb"
]
clean-nbs = "python docs/nbstripout.py"
format = [
"_ruff_format",
"_ruff_format_nb",
"_black_format"
]
_autogen_rst = "python docs/autogen_rst.py"
@@ -152,10 +130,8 @@ doc-build = [
"_sphinx_build"
]
_mypy = "mypy src/serena"
_mypy_nb = "nbqa mypy docs"
type-check = [
"_mypy",
"_mypy_nb"
]
[tool.ruff]