TL: CHANGELOG as link in README, fixed refs

Author: tlunet

CONTRIBUTING.md

@@ -1,15 +1,16 @@
 # How to contribute to pySDC
 
-1. [Pull Requests Recommendations](./docs/contrib/01_pull_requests.md)
-2. [Continuous Integration](./docs/contrib/02_continuous_integration.md)
-3. [Naming Conventions](./docs/contrib/03_naming_conventions.md)
-4. [Custom Implementations](./docs/contrib/04_custom_implementations.md)
-
-Developments on the `pySDC` code use the classical approach of forks and pull requests from Github.
-There is an [extended documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models) on this aspect (that you can skip if you are already used to it). In addition, some recommendations for pull requests are given [here](./docs/contrib/01_pull_requests.md).
+Developments on the `pySDC` code use the classical approach of forks and pull requests.
+You can look at [extended GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models) for more details (skip this if you are already used to it). Furthermore, branches on `pySDC` follow a pre-defined structure. To contribute to any of them, please look at the [pull request recommendations](./docs/contrib/01_pull_requests.md).
 
 Additionally, a _few_ rules are set to enforce code readability, consistency and reliability. Some of them are automatically tested with each commit, and summarized in the page on [continuous integration (CI)](./docs/contrib/02_continuous_integration.md).
-Others are specific conventions chosen for the pySDC library, that may follow Python standards (or not ...), detailed in the [naming conventions page](./docs/contrib/03_naming_conventions.md).
+Others are specific conventions chosen for the pySDC library, that may follow Python standards (or not ...), detailed in the [naming conventions](./docs/contrib/03_naming_conventions.md) page.
 
 Finally, while `pySDC` provides many base functionalities that implement classical flavors of SDC, it also allows problem-specific applications through Object-Oriented Programming (OOP) and the implementation of custom inherited classes.
-This follows a specific OOP framework, for which more details are given [here](./docs/contrib/04_custom_implementations.md).
+This follows a specific OOP framework, you can look at the page on [custom implementations](./docs/contrib/04_custom_implementations.md) for more details.
+
+1. [GitHub Forks and Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)
+2. [Pull Requests Recommendations](./docs/contrib/01_pull_requests.md)
+3. [Continuous Integration](./docs/contrib/02_continuous_integration.md)
+4. [Naming Conventions](./docs/contrib/03_naming_conventions.md)
+5. [Custom Implementations](./docs/contrib/04_custom_implementations.md)

README.md

@@ -89,8 +89,10 @@ The current software release can be cited using Zenodo:
 ## Contributing
 
 `pySDC` code was originally developed by [Robert Speck (@pancetta)](https://github.com/pancetta),
-and is now maintained and developed by a small community of scientists interested in SDC methods, that dearly welcomes any contribution.
-If you want to take part of this, please take the time to read our [Contribution Guidelines](./CONTRIBUTING.md)
+and is now maintained and developed by a small community of scientists interested in SDC methods.
+Checkout the [Changelog](./CHANGELOG.md) to see pySDC's evolution since 2016.
+
+Any contribution is dearly welcome ! If you want to take part of this, please take the time to read our [Contribution Guidelines](./CONTRIBUTING.md)
 (and don't forget to take a pick at our nice [Code of Conduct](./CODE_OF_CONDUCT.md) :wink:).
 
 

docs/contrib/02_continuous_integration.md

@@ -6,7 +6,7 @@ Finally, the CI also build artifacts that are used to generate the documentation
 
 ## Code linting
 
-Code style linting is performed using [`black`](https://black.readthedocs.io/en/stable/) and [`flakeheaven`](https://flakeheaven.readthedocs.io/en/latest/) for code syntax checking. In particular, `black` is used to check compliance with (most of) [PEP-8 guidelines](https://peps.python.org/pep-0008/).
+Code style linting is performed using [black](https://black.readthedocs.io/en/stable/) and [flakeheaven](https://flakeheaven.readthedocs.io/en/latest/) for code syntax checking. In particular, `black` is used to check compliance with (most of) [PEP-8 guidelines](https://peps.python.org/pep-0008/).
 
 Those tests are conducted for each commit (even for forks), but you can also run it locally in the root folder of `pySDC` before pushing any commit :
 
@@ -32,7 +32,7 @@ Some style rules that are automatically enforced :
 
 ## Code testing
 
-This is done using[ `pytest`](https://docs.pytest.org/en/7.2.x/), and runs all the tests written in the `pySDC/tests` folder. You can run those locally in the root folder of `pySDC` using :
+This is done using [pytest](https://docs.pytest.org/en/7.2.x/), and runs all the tests written in the `pySDC/tests` folder. You can run those locally in the root folder of `pySDC` using :
 
 ```bash
 # Install required packages (works also with conda/mamba)
@@ -50,7 +50,10 @@ pytest -v pySDC/tests
 
 ## Documentation generation
 
-To check the documentation generation, you can wait for all the CI tasks to download the `docs` artifacts, unzip it and open the `index.html` file there with you favorite browser. However, when you are working on documentation (of the project, of the code, etc ...), you can already build and check the website locally :
+Documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/).
+To check its generation, you can wait for all the CI tasks to download the `docs` artifacts, unzip it and open the `index.html` file there with you favorite browser. 
+
+However, when you are working on documentation (of the project, of the code, etc ...), you can already build and check the website locally :
 
 ```bash
 # Run all tests, continuing even with errors
@@ -68,4 +71,5 @@ Then you can open `docs/build/html/index.html` using you favorite browser and ch
 > This approach can be considered for local testing of your contribution when it does not concern parts containing images (_i.e_ project or code documentation).
 
 :arrow_left: [Back to Pull Request Recommendation](./01_pull_requests.md) ---
+:arrow_up: [Contributing Summary](./../../CONTRIBUTING.md) ---
 :arrow_right: [Next to Naming Conventions](./03_naming_conventions.md)

docs/contrib/03_naming_conventions.md

@@ -140,4 +140,5 @@ class MySweeper(Sweeper):
 ```
 
 :arrow_left: [Back to Continuous Integration](./02_continuous_integration.md) ---
+:arrow_up: [Contributing Summary](./../../CONTRIBUTING.md) ---
 :arrow_right: [Next to Custom Implementations](./04_custom_implementations.md)

docs/contrib/04_custom_implementations.md

@@ -3,4 +3,5 @@
 ... in construction ...
 
 :arrow_left: [Back to Naming Conventions](./03_naming_conventions.md) ---
+:arrow_up: [Contributing Summary](./../../CONTRIBUTING.md) ---
 :arrow_right: [Next to a cute picture of cat](https://www.vecteezy.com/photo/2098203-silver-tabby-cat-sitting-on-green-background)

docs/convert_markdown.py

@@ -61,22 +61,29 @@ def completeRefLinks(rst, baseName):
             i += 6
     return rst
 
-def convert(md):
+def addOrphanTag(rst):
+    return '\n:orphan:\n'+rst
+
+def convert(md, orphan=False, sectionRefs=True):
     baseName = os.path.splitext(md)[0]
     rst = m2r2.parse_from_file(md, parse_relative_links=True)
     rst = wrappEmojis(rst)
-    rst = addSectionRefs(rst, baseName)
+    if sectionRefs:
+        rst = addSectionRefs(rst, baseName)
     rst = completeRefLinks(rst, baseName)
+    if orphan:
+        rst = addOrphanTag(rst)
     with open(f'{docSources}/{baseName}.rst', 'w') as f:
         f.write(rst)
     print(f'Converted {md} to {docSources}/{baseName}.rst')
 
 for md in mdFiles:
     if os.path.isfile(md):
-        convert(md)
+        isNotMain = (md != 'README.md')
+        convert(md, orphan=isNotMain, sectionRefs=isNotMain)
     elif os.path.isdir(md):
         os.makedirs(f'{docSources}/{md}', exist_ok=True)
         for f in glob.glob(f'{md}/*.md'):
-            convert(f)
+            convert(f, orphan=True)
     else:
         raise ValueError('{md} is not a md file or a folder')

docs/source/conf.py

@@ -108,6 +108,7 @@
 # unit titles (such as .. function::).
 #
 add_module_names = False
+toc_object_entries_show_parents = 'hide'
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.

docs/source/index.rst

@@ -1,6 +1,13 @@
+
 .. include:: README.rst
 
-.. include:: CHANGELOG.rst
+Tests
+-----
+
+.. include:: ../../pySDC/tests/README.rst
+
+User Guide
+==========
 
 Tutorial
 --------
@@ -44,12 +51,6 @@ Projects
    projects/Resilience.rst
 
 
-Tests
------
-
-.. include:: ../../pySDC/tests/README.rst
-
-
 API documentation
 -----------------
 
@@ -63,11 +64,8 @@ API documentation
    pySDC/helpers.rst
 
 
-Indices and tables
-------------------
+Indices and tables :
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
-
+* :ref:`search`

pySDC/implementations/sweeper_classes/Runge_Kutta.py

@@ -135,10 +135,12 @@ class RungeKutta(generic_implicit):
     method, which does not require us to solve a system of equations to compute the stages.
 
     Please be aware that all fundamental parameters of the Sweeper are ignored. These include
+
      - num_nodes
      - collocation_class
      - initial_guess
      - QI
+
     All of these variables are either determined by the RK rule, or are not part of an RK scheme.
 
     Attribues:
@@ -245,9 +247,9 @@ def __init__(self, params):
 
 
 class CrankNicholson(RungeKutta):
-    '''
+    """
     Implicit Runge-Kutta method of second order
-    '''
+    """
 
     def __init__(self, params):
         nodes = np.array([0, 1])
@@ -260,9 +262,9 @@ def __init__(self, params):
 
 
 class MidpointMethod(RungeKutta):
-    '''
+    """
     Runge-Kutta method of second order
-    '''
+    """
 
     def __init__(self, params):
         implicit = params.get('implicit', False)
@@ -281,9 +283,9 @@ def __init__(self, params):
 
 
 class RK4(RungeKutta):
-    '''
+    """
     Explicit Runge-Kutta of fourth order: Everybodies darling.
-    '''
+    """
 
     def __init__(self, params):
         nodes = np.array([0, 0.5, 0.5, 1])
@@ -297,9 +299,9 @@ def __init__(self, params):
 
 
 class Heun_Euler(RungeKutta):
-    '''
+    """
     Second order explicit embedded Runge-Kutta
-    '''
+    """
 
     def __init__(self, params):
         nodes = np.array([0, 1])
@@ -311,9 +313,9 @@ def __init__(self, params):
 
 
 class Cash_Karp(RungeKutta):
-    '''
+    """
     Fifth order explicit embedded Runge-Kutta
-    '''
+    """
 
     def __init__(self, params):
         nodes = np.array([0, 0.2, 0.3, 0.6, 1.0, 7.0 / 8.0])