From 6bac193438c83457aced8d940b4514800087f794 Mon Sep 17 00:00:00 2001 From: Ulysse Herbach <35532736+ulysseherbach@users.noreply.github.com> Date: Wed, 9 Oct 2024 20:49:31 +0200 Subject: [PATCH] basic settings --- README.md | 1 + docs/_static/custom.css | 47 +++++-------------- docs/api/index.md | 22 +++++++++ docs/conf.py | 97 +++++++++++++++++++++++++++++++++------- docs/index.md | 22 +++++++++ docs/index.rst | 11 ----- docs/quickstart/index.md | 17 +++++++ docs/requirements.txt | 1 + 8 files changed, 155 insertions(+), 63 deletions(-) create mode 100644 docs/api/index.md create mode 100644 docs/index.md delete mode 100644 docs/index.rst create mode 100644 docs/quickstart/index.md diff --git a/README.md b/README.md index f84e5d1..4aa7342 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,3 @@ # FluffyClone +[![GitHub Release](https://img.shields.io/github/v/release/ulysseherbach/fluffyclone?logo=github)](https://github.com/ulysseherbach/fluffyclone) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 1f95aff..69fd436 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,46 +1,21 @@ -html[data-theme="dark"] .mermaid svg { - filter: invert(); -} - -html[data-theme="dark"] .bd-content div.cell_output img { - padding: unset; -} - -html[data-theme="dark"] .hide summary { - background-color: #29313d !important; - color: #EEFFFF; -} -.bd-search { +a.reference { border: 0; - border-radius: .5rem; -} - -div.cell details.above-input > summary { - border-bottom: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; } -div.cell details.above-input div.cell_input { - border-top: var(--mystnb-source-border-width) var(--mystnb-source-border-color) solid; -} - -.nbinput button.copybtn { - top: 0.3em; -} - -.nboutput button.copybtn, -.cell_output button.copybtn { - display: none; +a.reference.external:hover { + border: 0; } -button.btn.version-switcher__button { - margin-bottom: unset +div.sphinxsidebar a { + border: 0; } -div.cell_output tbody tr:nth-child(2n+1){ - background: unset; +h1.logo a:hover { + border: 0; } -div.cell_output tbody tr:hover { - background: rgba(66, 165, 245, 0.2); - } \ No newline at end of file +/*.bd-search { + border: 0; + border-radius: .5rem; +}*/ diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..aa81677 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,22 @@ +# API documentation + +## Sub modules + +```{eval-rst} +.. autosummary:: + :toctree: . + :nosignatures: + :recursive: + + fluffyclone.base +``` + +## Modules + +```{eval-rst} +.. autosummary:: + :toctree: . + :nosignatures: + + fluffyclone.base +``` diff --git a/docs/conf.py b/docs/conf.py index e9c4da3..dfe5102 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,39 +7,102 @@ # -- General configuration --------------------------------------------------- -extensions = [] +extensions = [ + 'myst_parser', + 'sphinx_copybutton', + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.autosummary', + # 'sphinx_multiversion', + # 'sphinx_sitemap', +] templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README*', + 'api' +] +source_suffix = {'.md': 'markdown', '.rst': 'restructuredtext'} # -- Options for HTML output ------------------------------------------------- +html_title = 'FluffyClone documentation' html_baseurl = 'https://ulysseherbach.github.io/fluffyclone/' html_static_path = ['_static'] html_css_files = ['custom.css'] -# html_copy_source = False -html_theme = 'pydata_sphinx_theme' +# html_sidebars = { +# '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'], +# } + +# html_theme = 'sphinx_book_theme' + +html_theme = 'alabaster' html_theme_options = { - 'icon_links': [ - { - 'name': 'GitHub', - 'url': 'https://github.com/ulysseherbach/fluffyclone', - 'icon': 'fa-brands fa-github', - 'type': 'fontawesome', - } - ], - 'pygments_light_style': 'default', - 'pygments_dark_style': 'material', + 'fixed_sidebar': True, + # 'logo': 'logo.png', + # 'github_user': 'ulysseherbach', + # 'github_repo': 'fluffyclone', } +# html_theme = 'pydata_sphinx_theme' +# html_theme_options = { +# 'icon_links': [ +# { +# 'name': 'GitHub', +# 'url': 'https://github.com/ulysseherbach/fluffyclone', +# 'icon': 'fa-brands fa-github', +# 'type': 'fontawesome', +# } +# ], +# 'pygments_light_style': 'default', +# 'pygments_dark_style': 'material', +# } + +# -- Options for sphinx.ext.autodoc ------------------------------------------ +# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + +# Automatically extract typehints when specified and place them in +# descriptions of the relevant function/method +autodoc_typehints = 'description' + +# Don't show class signature with the class' name +autodoc_class_signature = 'separated' + +# -- Options for sphinx.ext.napoleon ----------------------------------------- + +napoleon_google_docstring = False +napoleon_numpy_docstring = True + +# -- Options for sphinx.ext.autosummary -------------------------------------- + +autosummary_generate = True +autosummary_ignore_module_all = False +# autosummary_imported_members = True + +# -- Options for myst_parser ------------------------------------------------- + +myst_enable_extensions = [ + 'colon_fence', + # 'amsmath', + # 'dollarmath', + # 'strikethrough', + # 'tasklist', +] + +# -- Options for sphinx-copybutton ------------------------------------------ +# https://sphinx-copybutton.readthedocs.io/en/latest + +copybutton_exclude = '.linenos, .gp, .go' +copybutton_prompt_text = r'[$!]\s*' +copybutton_prompt_is_regexp = True + # -- Project information ----------------------------------------------------- -project = 'FluffyClone' +# project = 'FluffyClone' copyright = '2024, Ulysse Herbach' author = 'Ulysse Herbach' -# -- Dynamic information ----------------------------------------------------- +# -- Dynamic settings -------------------------------------------------------- # Get current version try: @@ -48,3 +111,5 @@ raise RuntimeError('fluffyclone must be installed for autodoc to work.') release = version +project = f'FluffyClone {version}' +# html_title = f'FluffyClone {version} documentation' diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4316bd3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ +# Welcome to FluffyClone docs + +:::{include} ../README.md +:start-line: 2 +::: + +:::{warning} +This documentation is still a draft. +::: + + +## Indexes + +* [General Index](genindex) +* [Module Index](modindex) + + +:::{toctree} +:hidden: + +quickstart/index +::: diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 50b45c0..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -FluffyClone documentation -========================= - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - -.. toctree:: - :maxdepth: 2 - :caption: Contents: diff --git a/docs/quickstart/index.md b/docs/quickstart/index.md new file mode 100644 index 0000000..cf5f418 --- /dev/null +++ b/docs/quickstart/index.md @@ -0,0 +1,17 @@ +# Quickstart + + +```{code-block} python +--- +emphasize-lines: 1, 2 +--- +a = 2 +print('my 1st line') +print(f'my {a}nd line') +``` + +```{code-block} python +a = 2 +print('my 1st line') +print(f'my {a}nd line') +``` diff --git a/docs/requirements.txt b/docs/requirements.txt index dfab548..c53eb3a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx pydata-sphinx-theme +myst-parser