Update Documentation

[katharinapaul2403]

This PR makes changes to CADET-RDM to address part of the To-Dos from Issue #80 and #76, improve readability and inconsistent nomenclature.

General changes

• modify documentation in user_guide and function descriptions to explain directory creation at initialization with path_to_repo
• use "directory", or "path" instead of "folder" (Inconsistent naming with folder / directory #76)
• change parameter name "output_folder_name" AND "output_repo_name" to "output_directory_name"
• change location of "rdm-testing-template" git repository via cloning from git@github.com:ronald-jaepel/rdm_testing_template.git to git@github.com:cadet/RDM-Testing-Template.git
• modify documentation structure: Introduction.md with explainations of the general concept of RDM added, getting-started.md modified to depict the most important commands and use-cases. CL/python/jupyter interface.md used for more detailled function descriptions

Changes needed to address failing tests

• test_git_adapter.py clones this personal GitHub respository: git@github.com:ronald-jaepel/rdm_testing_template.git in function try_initialize_from_remote() (Line 157)
• repositories.py (cadetrdm, Line 809) checks and processes the metadata taken from file "rdm_testing_template/.cadet-rdm-data.json" in this cloned repository
• cadet-rdm-data.json still contains the old name "output_folder_name". This line in the .json file would have to be renamed to "output_directory_name" to fix the failing test
• The rdm-testing-template remote repository is migrated to git@github.com:cadet/RDM-Testing-Template.git to address this issue

Documentation checked and modified

• installation.md
• getting-started.md
• CLI-interface
• jupyter-interface.md
• python-interface.md

Documentation changes

getting-started.md

• add short introduction text
• add description of created file structure at rdm initialization
• add description of adding remotes after their creation
• add description of staging and pushing changes via rdm check and rdm push

Command Line Interface

• change heading to "Using the Command Line Interface" (CLI interface == Command Line Interface Interface)
• "rdm data import" command is not intendet to be used as written in the current documentation. Implemented function is supposed to copy stationary data into the output directory. No option to specify branch or target directory implemented to enable loading a complete remote repository or foreign output repository. Current function (if used in a project repository with url=another rdm project OR output repository):
  Inside the output directory, new empty directories with the names of the imported project and output repositories are created. This takes place in a new branch. No other files are modified, including cadet-rdm-cache.json.
  Currently only useful to copy specific files, e.g. .py-files within a new branch to the output repository (by specifying url=source_project/output/specific_file.py) while also creating empty directories with the names of project and output repository from the source repository.
• function to update cadet-rdm-cache.json not working yet, has to be fixed to use rdm fetch and enable loading foreign output into a project repository.

[hannahlanzrath]

I have left some comments, thanks for the nice overhaul so far!

[hannahlanzrath]

Hi Katha,

Thanks so much for the great work you put into this!

With my last commit, I did some major structural changes, to harmonize the different sections a little more and make it more readable for the user. I also looked up some conventions for documenting CLI and Python and applied those. Lastly, I removed the hints about html files getting exported via the Jupyter Interface, as I have not seen that happen so far. Do you have any more info on this?

Please have a look at these changes. If you approve, I will refactor and merge.

[katharinapaul2403]

Hi Katha,

Thanks so much for the great work you put into this!

With my last commit, I did some major structural changes, to harmonize the different sections a little more and make it more readable for the user. I also looked up some conventions for documenting CLI and Python and applied those. Lastly, I removed the hints about html files getting exported via the Jupyter Interface, as I have not seen that happen so far. Do you have any more info on this?

Please have a look at these changes. If you approve, I will refactor and merge.

Hi Hannah,
I have tested the code from the previous jupyter interface documentation again, and it works as intended as far as I can see.
The following lines at the start and at the end of an .ipynb in an rdm repository do indeed save every run of the code by converting the .ipynb file into a .html file and dumping it aswell as the .ipynb into the output repository of the respective run branch.

from cadetrdm.repositories import JupyterInterfaceRepo

repo = JupyterInterfaceRepo()

repo.commit_nb_output(
    "path-to-the-current-notebook.ipynb",
    results_commit_message="Results commit message"
)

These lines internally call a convert_ipynb function, which uses the .ipynb specific package nbconvert.
The reason we (or at least I) have not used this in practice, is because our RDM examples are based on .py files and not native .ipynbs. Thus this code does not come into play in our examples.
As this feature does work as described in the previous documentation, I would suggest to keep it in the documentation as a whole, even if we personally don't have a use case for it yet.

As for your other changes, I like the adapted structure for better readability. Thanks for the adjustments!

[hannahlanzrath]

Hi Katha,

can you move these two points into a new issue, so we don't forget about them when I merge the PR?

• "rdm data import" command is not intendet to be used as written in the current documentation. Implemented function is supposed to copy stationary data into the output directory. No option to specify branch or target directory implemented to enable loading a complete remote repository or foreign output repository. Current function (if used in a project repository with url=another rdm project OR output repository):
  Inside the output directory, new empty directories with the names of the imported project and output repositories are created. This takes place in a new branch. No other files are modified, including cadet-rdm-cache.json.
  Currently only useful to copy specific files, e.g. .py-files within a new branch to the output repository (by specifying url=source_project/output/specific_file.py) while also creating empty directories with the names of project and output repository from the source repository.
• function to update cadet-rdm-cache.json not working yet, has to be fixed to use rdm fetch and enable loading foreign output into a project repository.