From 096934e795727bd6e4c154b39ddc117689976ffa Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Thu, 20 Mar 2025 15:08:18 +0100 Subject: [PATCH] Optimized docs --- 08_DEVELOPE.rst | 4 ---- 08_DEVELOPER_GUIDE.rst | 4 ++++ ...ISE_SOLUTIONS.md => 09_ENTERPRISE_SOLUTIONS.md | 0 10_INVESTOR_INFORMATIONS.md | 1 + 09_DONATE.md => 11_DONATE.md | 0 CONTRIBUTING.md | 4 ++-- Makefile | 10 +++++----- docs/Makefile | 15 +++++++++------ docs/conf.py | 6 +++--- docs/generators/yaml_index.py | 4 +++- index.rst | 2 +- 11 files changed, 28 insertions(+), 22 deletions(-) delete mode 100644 08_DEVELOPE.rst create mode 100644 08_DEVELOPER_GUIDE.rst rename 10_ENTERPRISE_SOLUTIONS.md => 09_ENTERPRISE_SOLUTIONS.md (100%) create mode 100644 10_INVESTOR_INFORMATIONS.md rename 09_DONATE.md => 11_DONATE.md (100%) diff --git a/08_DEVELOPE.rst b/08_DEVELOPE.rst deleted file mode 100644 index 0dc39d0c..00000000 --- a/08_DEVELOPE.rst +++ /dev/null @@ -1,4 +0,0 @@ -Developer Guide -=============== - -:doc: docs/generated/yaml_index.rst \ No newline at end of file diff --git a/08_DEVELOPER_GUIDE.rst b/08_DEVELOPER_GUIDE.rst new file mode 100644 index 00000000..8929d7b1 --- /dev/null +++ b/08_DEVELOPER_GUIDE.rst @@ -0,0 +1,4 @@ +Developer Guide +=============== + +To get an overview over all yaml files check out :doc:`docs/generated/yaml_index`. \ No newline at end of file diff --git a/10_ENTERPRISE_SOLUTIONS.md b/09_ENTERPRISE_SOLUTIONS.md similarity index 100% rename from 10_ENTERPRISE_SOLUTIONS.md rename to 09_ENTERPRISE_SOLUTIONS.md diff --git a/10_INVESTOR_INFORMATIONS.md b/10_INVESTOR_INFORMATIONS.md new file mode 100644 index 00000000..72ddf0d6 --- /dev/null +++ b/10_INVESTOR_INFORMATIONS.md @@ -0,0 +1 @@ +# Investor Informations \ No newline at end of file diff --git a/09_DONATE.md b/11_DONATE.md similarity index 100% rename from 09_DONATE.md rename to 11_DONATE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 715963ec..9f250946 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,10 +5,10 @@ Thank you for your interest in contributing to CyMaIS! We welcome contributions ## How to Contribute There are several ways you can help: -- **Reporting Issues:** Found a bug or have a feature request? Please open an issue on our [GitHub Issues page](https://github.com/your-repo-link/issues) with a clear description and steps to reproduce the problem. +- **Reporting Issues:** Found a bug or have a feature request? Please open an issue on our [GitHub Issues page](https://github.com/kevinveenbirkenbach/cymais/issues) with a clear description and steps to reproduce the problem. - **Code Contributions:** If you'd like to contribute code, fork the repository, create a new branch for your feature or bug fix, and submit a pull request. Ensure your code adheres to our coding style and includes tests where applicable. - **Documentation:** Improving the documentation is a great way to contribute. Whether it's clarifying an existing section or adding new guides, your contributions help others understand and use CyMaIS effectively. -- **Financial Contributions:** If you appreciate CyMaIS and want to support its ongoing development, consider making a financial contribution. For more details, please see our [06_DONATE.md](06_DONATE.md) file. +- **Financial Contributions:** If you appreciate CyMaIS and want to support its ongoing development, consider making a financial contribution. For more details, please see our [donate options](11_DONATE.md). ## Code of Conduct diff --git a/Makefile b/Makefile index a920ce17..6f0489fd 100644 --- a/Makefile +++ b/Makefile @@ -1,12 +1,12 @@ .PHONY: install deinstall refresh install: - $(MAKE) -C sphinx html $(MAKEFLAGS) - $(MAKE) -C sphinx install $(MAKEFLAGS) + $(MAKE) -C docs html $(MAKEFLAGS) + $(MAKE) -C docs install $(MAKEFLAGS) deinstall: - $(MAKE) -C sphinx clean $(MAKEFLAGS) + $(MAKE) -C docs clean $(MAKEFLAGS) refresh: - $(MAKE) -C sphinx clean $(MAKEFLAGS) - $(MAKE) -C sphinx html $(MAKEFLAGS) + $(MAKE) -C docs clean $(MAKEFLAGS) + $(MAKE) -C docs html $(MAKEFLAGS) diff --git a/docs/Makefile b/docs/Makefile index dab95cd3..5b073fe9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,10 +20,6 @@ generate-apidoc: @echo "Running sphinx-apidoc..." sphinx-apidoc -f -o $(SPHINX_GENERATED_DIR)/modules $(SPHINX_SOURCE_DIR) -remove-generated: - @echo "Removing generated files..." - - find $(SPHINX_GENERATED_DIR)/ -type f ! -name '.gitkeep' -delete - generate-yaml-index: @echo "Generating YAML index..." python generators/yaml_index.py --source-dir $(SPHINX_SOURCE_DIR) --output-file $(SPHINX_GENERATED_DIR)/yaml_index.rst @@ -32,16 +28,23 @@ generate-ansible-roles: @echo "Generating Ansible roles documentation..." python generators/ansible_roles.py --roles-dir $(SPHINX_SOURCE_DIR)/roles --output-dir $(SPHINX_GENERATED_DIR)/roles +remove-generated: + @echo "Removing generated files..." + - find $(SPHINX_GENERATED_DIR)/ -type f ! -name '.gitkeep' -delete + # "help" target does not copy images help: @$(SPHINXBUILD) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) -html: copy-images generate-apidoc generate-yaml-index generate-ansible-roles +html: copy-images generate-apidoc generate-ansible-roles generate-yaml-index + @$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) + +just-html: @$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) clean: remove-generated - @$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M clean "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/conf.py b/docs/conf.py index e01c2dc0..f9ae846f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,16 +52,16 @@ html_theme_options = { } source_suffix = { - '.rst': 'restructuredtext', '.md': 'markdown', + '.rst': 'restructuredtext', '.yml': 'restructuredtext', '.yaml': 'restructuredtext', } sys.path.insert(0, os.path.abspath('./extensions')) + extensions = [ - 'sphinx.ext.autosummary', - 'sphinx.ext.autodoc', + #'sphinx.ext.autosummary', 'myst_parser', 'extensions.local_file_headings', 'extensions.local_subfolders', diff --git a/docs/generators/yaml_index.py b/docs/generators/yaml_index.py index 24b75249..c1cea76c 100644 --- a/docs/generators/yaml_index.py +++ b/docs/generators/yaml_index.py @@ -36,7 +36,9 @@ def generate_yaml_index(source_dir, output_file): f.write("This document lists all `.yaml` and `.yml` files found in the specified directory, excluding ignored files.\n\n") for file in sorted(yaml_files): - f.write(f".. literalinclude:: {file}\n :language: yaml\n :linenos:\n\n") + relative_file_path = os.path.relpath(file, start=os.path.dirname(output_file)) + f.write(f".. literalinclude:: {relative_file_path}\n :language: yaml\n :linenos:\n\n") + print(f"YAML index has been generated at {output_file}") diff --git a/index.rst b/index.rst index d080d163..a6221f3e 100644 --- a/index.rst +++ b/index.rst @@ -1,4 +1,4 @@ About =============================== -.. markdown-include:: ../README.md \ No newline at end of file +.. markdown-include:: ./README.md \ No newline at end of file