Configuring the documentation for Sphinx and ReadTheDocs

[joe-from-mtl]

Stacked PR 12/22 — review order: #115 → #97 → #98 → #99 → #100 → #101 → #108 → #106 → #107 → #87 → #116 → #110 → #111 → #40 → #112 → #113 → #117 → #118 → #120 → #121 → #122 → #123 → #124 → #125

Base: pr-tail-cleanup. Retargets to main as upstream PRs merge.

---

This PR adresses the following issues

• Check if scripts in linumpy-private are useful #30
• Remove shell_scripts and move to documentation #36
• Uniformize the docstring to use numpy style #37

[pep8speaks]

Hello @joe-from-mtl! Thanks for updating this PR.

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2024-12-17 21:22:34 UTC

[CHrlS98]

What are those?

[CHrlS98]

Attribute description?

[CHrlS98]

Missing : no?

[CHrlS98]

can you fix the linum_detect_focalCurvature.py too?

[CHrlS98]

We should also mention somewhere than the zarr chunk size is often chosen to match the raw tile size. This is important for the processing pipeline.

[FIrgolitsch]

I was looking at this for my own additions, but I think we should agree on a style first. For LIOM Toolkit I have been using docstrings like this for readthedocs:

def get_folder_list(tiles_directory: Path) -> list[Path]:
    """
    List all the tiles in a given directory.

    :param tiles_directory: Path to the directory containing the tiles.
    :type tiles_directory: Path
    :return: List of tile file paths.
    :rtype: list[Path]
    """

I based this off of the Sphinx-RTD documentation:
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html

It's a bit less verbose than what we have, but I prefer this as it leaves a lot less whitespace compared to:

def generate_default(nX, nY):
    """Generates a default topology where all tiles in mosaic are nodes and all neighbor relation is an edge.
    Parameters
    ----------
    nX: int
        Number of tiles in X direction.
    nY: int
        Number of tiles in Y direction.

    Returns
    -------
    mosaicTopo : NetworkX graph object describing the mosaic topology

    Note
    ----
    Each node position (in tile reference) can be accessed as node attributes 'x' and 'y'.

    """

[CHrlS98]

@FIrgolitsch can you add a comment to this issue #59 . Let's brainstorm there for what coding standards we want to follow

Also, in scilpy we use the second option so it is what I am used to, but I wouldn't mind going for the first option. We only need to be constant across the codebase.

[FIrgolitsch]

Found this PR still open and figured I'd fix this one too. This can be merged after #111 .