Update Documentation #87

katharinapaul2403 · 2025-08-20T15:44:50Z

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

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 · 2025-09-24T06:16:34Z

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.


I think we can ditch the IntelliSense entry?

Yes, I actually didn't mean to include this .vscode directory in the CADET-RDM push at all. It was automatically generated while I changed my configurations. I will remove the whole directory with my next push.

Ah I see, you can just add .vscode to .gitignore in the RDM folder, that will solve it!

That's right, I didn't even think of that! Thanks

hannahlanzrath · 2025-09-24T06:18:28Z

AUTHORS.md

@@ -0,0 +1,14 @@
+# Contributors
+
+The following individuals have made significant contributions to the CADET-RDM software and are listed in *chronological order*. Together they form the "CADET-RDM authors" as mentioned in the copyright statements.


I would leave the Introduction Sentences out here, so we just have "Contributors", then the Names.

Order: Ron, Hannah, Jo, Katha, Daniel, Eric

Okay, no problem. I will also change this in the cookiecutter template. This could also be changed in the CADET-Core AUTHORS.md if necessary.

hannahlanzrath · 2025-09-24T06:20:33Z

docs/source/user_guide/command-line-interface.md

-To share your project code and results with others, you need to create remote repositories on e.g.
-[GitHub](https://github.com/) or GitLab. You need to create a remote for both the _project_ repo and the
-_results_ repo.
+To share your project code and results (`output`) with others, you need to create remote repositories on e.g.


Passive speech would be better here, so e.g.

"To share a project code and results (output) with others, a remote repository has to be created..."

Just to avoid "You"

Got it, the direct "You" is currently used very often in the documentation and the descriptions and comments in the source code. I can try to at least change the wording in the documentation.

hannahlanzrath · 2025-09-24T06:21:09Z

docs/source/user_guide/command-line-interface.md


-Once remotes are configured, you can push all changes to the project repo and the results repos with the
-command
+Once remotes are configured, you can push all changes to the project repository and the output repository with the following command from within the project repository:


Same here, so something like

"Once remotes are configured, all changes can be pushed to the project repository and the output repository with the following command from within the project repository..."

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

extend documentation to explain creation of new directories with path_to_repo, change parameter name from output_folder_name to output_directory_name, modify descriptions to use path and directory instead of folder Fix Unicode Error by escaping path name in function description by using "\\U..." instead of "\U..." rename output_folder to output_directory Change remote path in test_git_adapter.py function try_initialize_from_remote from git@github.com:ronald-jaepel/rdm_testing_template.git to git@github.com:cadet/RDM-Testing-Template.git to account for renaming changes Update location for remote repository rdm-testing template Explain optional cookiecutter support in more detail Modify documentation: expand upon introduction, add description of file structure, rename CLI documentation Fix typos Change output_repo_name to output_directory_name Update branch name documentation, change folder to directory in documentation and descriptions Add AUTHORS, CITATION, CODE_OF_CONDUCT, SECURITY.md Remove unimplemented cli function to load results from another repository via cadet-rdm-cache.json from documentation Expand rdm clone documentation Change AUTHORS.md order, use indirect speech in documentation, fix function parameters in documentation Modify getting started, add .vscode to gitignore Add Introduction in docs Add Git-LFS installation guide, modify documentation structure Add myst_parser, modify bibliography.md to cite all references Add image directory, modify image creation with sphinx syntax Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Applies naming conventions to comments, docs and variables. Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

katharinapaul2403 requested a review from hannahlanzrath August 20, 2025 15:44

katharinapaul2403 self-assigned this Aug 20, 2025

hannahlanzrath requested changes Sep 24, 2025

View reviewed changes

katharinapaul2403 and others added 14 commits October 1, 2025 13:54

Update readthedocs to access dependency groups

57852d6

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update and add meta files for GitHub

3f9f5e0

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update private repositories in tests

ee934fb

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Add sphinx_subfigure to configuration

ccee45b

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Fix typos and directy speech

6065a72

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update Jupyter interface in documentation

73a60c5

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update Python interface in documentation

b292e80

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update installation guide in documentation

fce0a5a

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update getting started in documentation

2821b37

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Update CLI Inteface Documentation

af63b3e

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Change "folder" to "directory" or "path"

e63072a

Applies naming conventions to comments, docs and variables. Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Add introduction to toctree

9eb0aec

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

Add package excludes to toml

37fd84f

Co-authored-by: Hannah Lanzrath <h.lanzrath@fz-juelich.de>

hannahlanzrath force-pushed the update_documentation branch from 109c0e3 to 37fd84f Compare October 1, 2025 11:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update Documentation #87

Update Documentation #87

Uh oh!

katharinapaul2403 commented Aug 20, 2025 •

edited

Loading

Uh oh!

hannahlanzrath left a comment

Uh oh!

hannahlanzrath Sep 24, 2025

Uh oh!

katharinapaul2403 Sep 24, 2025

Uh oh!

hannahlanzrath Sep 24, 2025

Uh oh!

katharinapaul2403 Sep 25, 2025

Uh oh!

hannahlanzrath Sep 24, 2025

Uh oh!

katharinapaul2403 Sep 24, 2025

Uh oh!

hannahlanzrath Sep 24, 2025

Uh oh!

katharinapaul2403 Sep 24, 2025

Uh oh!

hannahlanzrath Sep 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,15 @@
		{
		// Use IntelliSense to learn about possible attributes.

		@@ -0,0 +1,14 @@
		# Contributors

		The following individuals have made significant contributions to the CADET-RDM software and are listed in chronological order. Together they form the "CADET-RDM authors" as mentioned in the copyright statements.

Update Documentation #87

Are you sure you want to change the base?

Update Documentation #87

Uh oh!

Conversation

katharinapaul2403 commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

General changes

Changes needed to address failing tests

Documentation checked and modified

Documentation changes

getting-started.md

Command Line Interface

Uh oh!

hannahlanzrath left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

katharinapaul2403 commented Aug 20, 2025 •

edited

Loading