From ea7a2c837a4f3beb5dc0625d8da86f10ac7e748f Mon Sep 17 00:00:00 2001 From: Nick Papior Date: Thu, 24 Oct 2024 09:50:05 +0200 Subject: [PATCH 1/2] major restructure of the documentation New sections, and moved the viz section to a more sensible name. Perhaps it should be changed altogether. Currently the ASE viz has been removed, is it even required? It might be easier to just document ASE conversion. Signed-off-by: Nick Papior --- .github/PULL_REQUEST_TEMPLATE.md | 13 +- .pre-commit-config.yaml | 17 ++- docs/conf.py | 12 +- docs/contribute.rst | 36 ----- docs/dev/index.rst | 139 ++++++++++++++++++ docs/index.rst | 31 ++-- docs/other.rst | 4 +- docs/references.rst | 4 +- docs/requirements.txt | 1 + .../basic-tutorials/Demo.ipynb | 0 .../blender/First animation.rst | 0 .../blender/Getting started.rst | 0 .../Intro to combining plots.ipynb | 0 .../diy/Adding new backends.ipynb | 0 .../diy/Building a new plot.ipynb | 0 .../{viz_module => viz}/index.rst | 2 +- .../showcase/AtomicMatrixPlot.ipynb | 0 .../showcase/BandsPlot.ipynb | 0 .../showcase/FatbandsPlot.ipynb | 0 .../showcase/GeometryPlot.ipynb | 0 .../showcase/GridPlot.ipynb | 0 .../showcase/PdosPlot.ipynb | 0 .../showcase/SitesPlot.ipynb | 0 .../showcase/WavefunctionPlot.ipynb | 0 .../_template/Showcase template.ipynb | 0 .../showcase/_template/create.py | 0 .../tests/test_tutorials.py | 0 pyproject.toml | 1 + 28 files changed, 194 insertions(+), 66 deletions(-) delete mode 100644 docs/contribute.rst create mode 100644 docs/dev/index.rst rename docs/visualization/{viz_module => viz}/basic-tutorials/Demo.ipynb (100%) rename docs/visualization/{viz_module => viz}/blender/First animation.rst (100%) rename docs/visualization/{viz_module => viz}/blender/Getting started.rst (100%) rename docs/visualization/{viz_module => viz}/combining-plots/Intro to combining plots.ipynb (100%) rename docs/visualization/{viz_module => viz}/diy/Adding new backends.ipynb (100%) rename docs/visualization/{viz_module => viz}/diy/Building a new plot.ipynb (100%) rename docs/visualization/{viz_module => viz}/index.rst (99%) rename docs/visualization/{viz_module => viz}/showcase/AtomicMatrixPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/BandsPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/FatbandsPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/GeometryPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/GridPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/PdosPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/SitesPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/WavefunctionPlot.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/_template/Showcase template.ipynb (100%) rename docs/visualization/{viz_module => viz}/showcase/_template/create.py (100%) rename docs/visualization/{viz_module => viz}/tests/test_tutorials.py (100%) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cfff5d4dc9..9aca1c0508 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,6 +2,17 @@ - [ ] Closes # - [ ] Added tests for new/changed functions? - - [ ] Ran `isort .` and `black .` [24.2.0] at top-level - [ ] Documentation for functionality in `docs/` - [ ] Changes documented in `CHANGELOG.md` + + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f241e3af7e..7672011b8a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -8,12 +8,12 @@ # If pre-commit does some modification, the commit will fail. Add the # changes done by pre-commit and commit again. repos: -- repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 - hooks: - - id: check-yaml - - id: end-of-file-fixer - - id: trailing-whitespace +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace # Black to format code with a consistent style - repo: https://github.com/psf/black-pre-commit-mirror rev: 24.2.0 @@ -44,3 +44,8 @@ repos: - --license-filepath - .LICENSE_header - --no-extra-eol +#Validate our CITATION.cff +- repo: https://github.com/citation-file-format/cff-converter-python + rev: ebf0b5e44d67f8beaa1cd13a0d0393ea04c6058d + hooks: + - id: validate-cff diff --git a/docs/conf.py b/docs/conf.py index cf9544c0f6..d0d98340fb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -70,7 +70,7 @@ # General information about the project. project = "sisl" -author = "Nick Papior" +author = "sisl developers" copyright = f"2015-{date.today().year}, {author}" @@ -92,6 +92,8 @@ "sphinx.ext.todo", # allows to view code directly in the homepage "sphinx.ext.viewcode", + # Enable redirections + "sphinxext.rediraffe", # toggle-button on info/warning/... "sphinx_togglebutton", # allow copybutton on code-blocks @@ -375,6 +377,12 @@ def has_no_under(name: str): html_use_index = True +# Redirects of moved pages +rediraffe_redirects = { + "contribute.rst": "dev/index.rst", + "visualization/viz_module/index.rst": "visualization/viz/index.rst", +} + latex_elements = { # The paper size ('letterpaper' or 'a4paper'). "papersize": "a4paper", @@ -390,7 +398,7 @@ def has_no_under(name: str): # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ("index", "sisl.tex", "sisl Documentation", "Nick Papior", "manual"), + ("index", "sisl.tex", project, author, "manual"), ] ##### diff --git a/docs/contribute.rst b/docs/contribute.rst deleted file mode 100644 index e45b6767d2..0000000000 --- a/docs/contribute.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _contributing: - -Contributing -============ - -The sisl code is open-source, and thus we encourage external users to contribute -back to the code base. - -Any size of contribution is extremely welcome! - -- If you've ideas of missing features -- If you've ideas for improving documentation -- If you've found a bug -- If you've found a documentation error -- If you've created a tutorial - -Then please share them `here `_. -It is recommended to test the development, please follow `these instructions `_. - -Contributing additional test files should be contributed `here `_. - - -Contribute external code ------------------------- - -External toolbox codes may be contributed `here `_, then press -"Issue" and select *Contribute toolbox*. - -There are two cases of external contributions: - -1. If the code is directly integratable into sisl it will be merged into the sisl source. - -2. If the code is showing how to use sisl to calculate some physical quantity but is not a general - implementation, it will be placed in toolbox directory. - -Either way, any contribution is very welcome. diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 0000000000..fd7f9e3a28 --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,139 @@ + +.. _devindex: + +Contributing to sisl +==================== + +The sisl code is open-source, and thus we encourage external users to contribute +back to the code base. + +Even if you are a non-coder, your contributions are valuable to the community! +Please do remember that open-source projects benefits from interaction! + +There are many aspects of useful contributions: + +- Code maintenance and development +- Creating tutorials and extending documentation +- Finding bugs or typos +- Development of the website +- Missing a useful feature + +We understand that people have different backgrounds, and thus different +experience in coding. We try to engage as much as possible with ticket creators. + +In the following of this document you will find information related to the specifics +of making a development workflow for `sisl`. + + + +Summary of development process +------------------------------ + + +Here is a short summary of how to do developments with `sisl`. + + +1. If you are a first time contributor, you need to clone your repository + and setup a few things. + + The procedure enables one to follow the upstream changes, while simultaneously + have a fork where one has write access. + + * Go to `github.com/zerothi/sisl `_ and click the "fork" button to + create your own copy of the code base. + + * Clone the fork to your local machine: + + .. code:: bash + + git clone https://github.com//sisl.git + + * Add the upstream repository: + + .. code:: bash + + git remote add upstream https://github.com/zerothi/sisl.git + + * Enable the `pre-commit `_ hooks + + .. code:: bash + + python -m pip install pre-commit + pre-commit install + + This will run specific checks before you commit things to the repo. + It ensures a consistency in the project. + +2. Installing the project in development mode. + + It is adviced to instal the project in *editable* mode for faster + turn-around times. + Please follow :ref:`these instructions `. + +3. Developing your contribution. + + First start by ensuring you have the latest changes on the ``main`` + branch. + + .. code:: bash + + git checkout main + git pull upstream main + + If you are fixing an already opened issue (say :issue:`42`) it is adviced + to name your branch according to the issue number following a sensible name: + + .. code:: bash + + git checkout -b 42-enhancing-doc + + If no issue has been created, then just name it sensibly. + + Do all your commits locally as you progress. + + Be sure to document your changes, and write sensible documentation + for the API. + +4. To submit your contribution: + + * Push your changes back to your fork on GitHub: + + .. code:: bash + + git push origin 42-enhancing-doc + + * Go to `sisl's pull request site `_. + The new branch will show up with a green Pull Request + button. Make sure the title and message are clear, concise, and self- + explanatory. Then click the button to submit it. + +5. Review process. + + The maintainers of `sisl` will do their best to respond as fast as possible. + But first ensure that the CI runs successfully, if not, maintainers will likely + wait untill it succeeds before taking any action. + + +Contribute external code +------------------------ + +External toolbox codes may be contributed `here `_, then press +"Issue" and select *Contribute toolbox*. + +There are two cases of external contributions: + +1. If the code is directly integratable into sisl it will be merged into the sisl source. + +2. If the code is showing how to use sisl to calculate some physical quantity but is not a general + implementation, it will be placed in toolbox directory. + +Either way, any contribution is very welcome. + + + +Contribute additional tests +--------------------------- + +Additional test files should be added to `this repository `_. +Please follow the guidelines there, or open up an issue at that repository +for specific details. diff --git a/docs/index.rst b/docs/index.rst index da0b179c6b..f755ad7609 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,46 +67,45 @@ Since then it has expanded to accommodate a rich set of DFT code input/outputs. .. toctree:: :hidden: :maxdepth: 2 - :caption: User Guide + :caption: Getting started introduction quickstart/index - tutorials/index - scripts/index - environment - math + cite .. toctree:: :hidden: :maxdepth: 2 - :caption: Visualization + :caption: User Guide - visualization/viz_module/index - visualization/ase/index + tutorials/index + visualization/viz/index + scripts/index .. toctree:: :hidden: :maxdepth: 2 - :caption: Toolboxes + :caption: Advanced usage + api/index + environment toolbox/index .. toctree:: :hidden: :maxdepth: 2 - :caption: Development details + :caption: Development - contribute - changelog/index - cite - other + dev/index .. toctree:: :hidden: :maxdepth: 3 - :caption: Reference documentation + :caption: Extras - api/index + math + changelog/index + other references diff --git a/docs/other.rst b/docs/other.rst index 2228d4137e..1714e4cb34 100644 --- a/docs/other.rst +++ b/docs/other.rst @@ -11,9 +11,9 @@ calculations. However, `sisl` is far from the only Python package that implements simplistic tight-binding calculations. We are currently aware of 3 established tight-binding methods used in literature (in random order): -- `PythTB `_ +- `PythTB `__ - `kwant`_ -- `pybinding `_ +- `pybinding `__ - `ASE`_ `sisl`'s philosophy is drastically different in the sense that the Hamiltonian (and other diff --git a/docs/references.rst b/docs/references.rst index 3e2e9a412e..386634b59c 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -1,7 +1,7 @@ .. _references: -References -========== +Bibliography +============ .. create the bibliography will all references. We may still use local footnote bib's for clarity. diff --git a/docs/requirements.txt b/docs/requirements.txt index dd993275a5..b8ab7b0f62 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -17,6 +17,7 @@ sphinx-copybutton sphinx-togglebutton sphinx-inline-tabs sphinxcontrib-bibtex +sphinxext-rediraffe importlib-metadata ipywidgets jupyterlab-widgets diff --git a/docs/visualization/viz_module/basic-tutorials/Demo.ipynb b/docs/visualization/viz/basic-tutorials/Demo.ipynb similarity index 100% rename from docs/visualization/viz_module/basic-tutorials/Demo.ipynb rename to docs/visualization/viz/basic-tutorials/Demo.ipynb diff --git a/docs/visualization/viz_module/blender/First animation.rst b/docs/visualization/viz/blender/First animation.rst similarity index 100% rename from docs/visualization/viz_module/blender/First animation.rst rename to docs/visualization/viz/blender/First animation.rst diff --git a/docs/visualization/viz_module/blender/Getting started.rst b/docs/visualization/viz/blender/Getting started.rst similarity index 100% rename from docs/visualization/viz_module/blender/Getting started.rst rename to docs/visualization/viz/blender/Getting started.rst diff --git a/docs/visualization/viz_module/combining-plots/Intro to combining plots.ipynb b/docs/visualization/viz/combining-plots/Intro to combining plots.ipynb similarity index 100% rename from docs/visualization/viz_module/combining-plots/Intro to combining plots.ipynb rename to docs/visualization/viz/combining-plots/Intro to combining plots.ipynb diff --git a/docs/visualization/viz_module/diy/Adding new backends.ipynb b/docs/visualization/viz/diy/Adding new backends.ipynb similarity index 100% rename from docs/visualization/viz_module/diy/Adding new backends.ipynb rename to docs/visualization/viz/diy/Adding new backends.ipynb diff --git a/docs/visualization/viz_module/diy/Building a new plot.ipynb b/docs/visualization/viz/diy/Building a new plot.ipynb similarity index 100% rename from docs/visualization/viz_module/diy/Building a new plot.ipynb rename to docs/visualization/viz/diy/Building a new plot.ipynb diff --git a/docs/visualization/viz_module/index.rst b/docs/visualization/viz/index.rst similarity index 99% rename from docs/visualization/viz_module/index.rst rename to docs/visualization/viz/index.rst index fb119aa6d4..39021b5d8e 100644 --- a/docs/visualization/viz_module/index.rst +++ b/docs/visualization/viz/index.rst @@ -2,7 +2,7 @@ .. _toc-sisl-viz: -``sisl.viz`` +Visualization ---------------------------- This is a full visualization framework developed specifically for ``sisl`` to visualize diff --git a/docs/visualization/viz_module/showcase/AtomicMatrixPlot.ipynb b/docs/visualization/viz/showcase/AtomicMatrixPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/AtomicMatrixPlot.ipynb rename to docs/visualization/viz/showcase/AtomicMatrixPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/BandsPlot.ipynb b/docs/visualization/viz/showcase/BandsPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/BandsPlot.ipynb rename to docs/visualization/viz/showcase/BandsPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/FatbandsPlot.ipynb b/docs/visualization/viz/showcase/FatbandsPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/FatbandsPlot.ipynb rename to docs/visualization/viz/showcase/FatbandsPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/GeometryPlot.ipynb b/docs/visualization/viz/showcase/GeometryPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/GeometryPlot.ipynb rename to docs/visualization/viz/showcase/GeometryPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/GridPlot.ipynb b/docs/visualization/viz/showcase/GridPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/GridPlot.ipynb rename to docs/visualization/viz/showcase/GridPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/PdosPlot.ipynb b/docs/visualization/viz/showcase/PdosPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/PdosPlot.ipynb rename to docs/visualization/viz/showcase/PdosPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/SitesPlot.ipynb b/docs/visualization/viz/showcase/SitesPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/SitesPlot.ipynb rename to docs/visualization/viz/showcase/SitesPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/WavefunctionPlot.ipynb b/docs/visualization/viz/showcase/WavefunctionPlot.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/WavefunctionPlot.ipynb rename to docs/visualization/viz/showcase/WavefunctionPlot.ipynb diff --git a/docs/visualization/viz_module/showcase/_template/Showcase template.ipynb b/docs/visualization/viz/showcase/_template/Showcase template.ipynb similarity index 100% rename from docs/visualization/viz_module/showcase/_template/Showcase template.ipynb rename to docs/visualization/viz/showcase/_template/Showcase template.ipynb diff --git a/docs/visualization/viz_module/showcase/_template/create.py b/docs/visualization/viz/showcase/_template/create.py similarity index 100% rename from docs/visualization/viz_module/showcase/_template/create.py rename to docs/visualization/viz/showcase/_template/create.py diff --git a/docs/visualization/viz_module/tests/test_tutorials.py b/docs/visualization/viz/tests/test_tutorials.py similarity index 100% rename from docs/visualization/viz_module/tests/test_tutorials.py rename to docs/visualization/viz/tests/test_tutorials.py diff --git a/pyproject.toml b/pyproject.toml index 0e36da3d82..bb1a5a0869 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -204,6 +204,7 @@ docs = [ "sphinx-togglebutton", "sphinx-inline-tabs", "sphinxcontrib-bibtex", + "sphinxext-rediraffe", "importlib-metadata", "ipykernel", "ipywidgets", From 1970cafea35c6b1eec75048275a9e82dd81c835c Mon Sep 17 00:00:00 2001 From: Nick Papior Date: Thu, 24 Oct 2024 09:56:47 +0200 Subject: [PATCH 2/2] changed Similar solutions to Related software Signed-off-by: Nick Papior --- docs/other.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/other.rst b/docs/other.rst index 1714e4cb34..47a93cc0d1 100644 --- a/docs/other.rst +++ b/docs/other.rst @@ -1,6 +1,6 @@ .. _other: -Similar solutions +Related software ================= One of `sisl`'s goals is an easy interaction between a variety of DFT simulations, much like `ASE`_ with