Merge pull request #851 from zerothi/doc-changes

major restructure of the documentation

.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`
+
+<!--
+Creating a PR will check whether the pre-commit hooks
+have runned, and if it fails, you should do this manually.
+
+Please see here: https://zerothi.github.io/sisl/contribute.html
+on how to enable the pre-commit hooks enabled in `sisl`
+
+The short message is:
+- run `isort .` at the top level
+- run `black .` (version=24.2.0) at top-level
+-->

.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

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"),
 ]
 
 #####

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 <sisl-git_>`_ 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/<your-username>/sisl.git
+
+   * Add the upstream repository:
+
+     .. code:: bash
+
+        git remote add upstream https://github.com/zerothi/sisl.git
+
+   * Enable the `pre-commit <https://pre-commit.com>`_ 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 <installation-testing>`.
+
+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 <pr_>`_.
+     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 <issue_>`_, 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 <sisl-files_>`_.
+Please follow the guidelines there, or open up an issue at that repository
+for specific details.

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
 
 

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
@@ -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 <http://physics.rutgers.edu/pythtb/index.html>`_
+- `PythTB <http://physics.rutgers.edu/pythtb/index.html>`__
 - `kwant`_
-- `pybinding <http://pybinding.site/>`_
+- `pybinding <http://pybinding.site/>`__
 - `ASE`_
 
 `sisl`'s philosophy is drastically different in the sense that the Hamiltonian (and other

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.

docs/requirements.txt

@@ -17,6 +17,7 @@ sphinx-copybutton
 sphinx-togglebutton
 sphinx-inline-tabs
 sphinxcontrib-bibtex
+sphinxext-rediraffe
 importlib-metadata
 ipywidgets
 jupyterlab-widgets

docs/visualization/viz_module/index.rst → 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

pyproject.toml

@@ -204,6 +204,7 @@ docs = [
     "sphinx-togglebutton",
     "sphinx-inline-tabs",
     "sphinxcontrib-bibtex",
+    "sphinxext-rediraffe",
     "importlib-metadata",
     "ipykernel",
     "ipywidgets",