From 11b73d098535410628ccadfb2250d4761e1a63c2 Mon Sep 17 00:00:00 2001 From: ZacharyH777 Date: Sun, 26 Jan 2025 15:05:16 -0800 Subject: [PATCH 1/3] This is a changed version of the engine3d website The website includes auto generation of doxygen xml which is then used by breath and sphinx. Breath hierarchy is also auto generated using doxygen xml. New side bar to showcase heirarchy and to integrate sphinx with mkdocs. What needs to be done, eventually. A tab should be built for each function that seperates the parameters, from our reasoning and examples. Title also needs to be fixed. Overall it needs to look better lol. Not my type of skill set though. --- .gitignore | 10 + Doxyfile_api | 21 + README.md | 23 + Sphinx/Makefile | 20 + Sphinx/make.bat | 35 + Sphinx/source/conf.py | 35 + Sphinx/source/generate_sphinx_dyn.py | 107 + Sphinx/source/index.rst | 7 + assets/extra.css | 38 - build_docs.ps1 | 46 + build_docs.sh | 53 + docs/Documentation/docs_home.md | 8 + docs/Documentation/engine3d_api_docs.md | 5 + docs/Documentation/engine3d_older_doc_list.md | 1 + docs/about.md | 2 +- docs/assets/CSS/extra_style.css | 160 ++ docs/assets/CSS/sphinx_api.css | 115 + docs/assets/JS/custome-nav.js | 176 ++ docs/assets/JS/dynamic-sidebar.js | 225 ++ docs/assets/JS/sphinx-mkdocs-converter.js | 104 + .../assets}/logos/engine3DHighResLogo.png | Bin .../assets}/logos/engine3dTransparentLogo.png | Bin docs/getting_started.md | 2 +- docs/tabs.md | 2 +- .../Test1_folder/example2_folder/camera.hpp | 87 + .../Test1_folder/math_utils.hpp | 73 + engine3d_website_test/string_utils.h | 50 + html/annotated.html | 123 + html/annotated_dup.js | 6 + html/bc_s.png | Bin 0 -> 676 bytes html/bc_sd.png | Bin 0 -> 635 bytes html/classes.html | 123 + ...classtest_space_1_1test__docs-members.html | 121 + html/classtest_space_1_1test__docs.html | 169 ++ html/classtest_space_1_1test__docs.js | 4 + html/clipboard.js | 61 + html/closed.png | Bin 0 -> 132 bytes html/cookie.js | 58 + .../dir_6bdf1cba9e98d2cc2b433b0ad246f0f0.html | 125 + html/dir_6bdf1cba9e98d2cc2b433b0ad246f0f0.js | 4 + html/doc.svg | 12 + html/docd.svg | 12 + html/doxygen.css | 2256 +++++++++++++++ html/doxygen.svg | 28 + html/doxygen_crawl.html | 27 + html/dynsections.js | 198 ++ html/files.html | 123 + html/files_dup.js | 4 + html/folderclosed.svg | 11 + html/folderclosedd.svg | 11 + html/folderopen.svg | 17 + html/folderopend.svg | 12 + html/functions.html | 117 + html/functions_func.html | 117 + html/index.html | 118 + html/jquery.js | 204 ++ html/minus.svg | 8 + html/minusd.svg | 8 + html/namespaces.html | 122 + html/namespaces_dup.js | 4 + html/namespacetest_space.html | 129 + html/namespacetest_space.js | 4 + html/nav_f.png | Bin 0 -> 153 bytes html/nav_fd.png | Bin 0 -> 169 bytes html/nav_g.png | Bin 0 -> 95 bytes html/nav_h.png | Bin 0 -> 98 bytes html/nav_hd.png | Bin 0 -> 114 bytes html/navtree.css | 149 + html/navtree.js | 483 ++++ html/navtreedata.js | 51 + html/navtreeindex0.js | 19 + html/open.png | Bin 0 -> 123 bytes html/plus.svg | 9 + html/plusd.svg | 9 + html/resize.js | 147 + html/search/all_0.js | 7 + html/search/classes_0.js | 4 + html/search/close.svg | 18 + html/search/files_0.js | 4 + html/search/functions_0.js | 4 + html/search/mag.svg | 24 + html/search/mag_d.svg | 24 + html/search/mag_sel.svg | 31 + html/search/mag_seld.svg | 31 + html/search/namespaces_0.js | 4 + html/search/search.css | 286 ++ html/search/search.js | 694 +++++ html/search/searchdata.js | 27 + html/splitbar.png | Bin 0 -> 314 bytes html/splitbard.png | Bin 0 -> 282 bytes html/sync_off.png | Bin 0 -> 853 bytes html/sync_on.png | Bin 0 -> 845 bytes html/tab_a.png | Bin 0 -> 142 bytes html/tab_ad.png | Bin 0 -> 135 bytes html/tab_b.png | Bin 0 -> 169 bytes html/tab_bd.png | Bin 0 -> 173 bytes html/tab_h.png | Bin 0 -> 177 bytes html/tab_hd.png | Bin 0 -> 180 bytes html/tab_s.png | Bin 0 -> 184 bytes html/tab_sd.png | Bin 0 -> 188 bytes html/tabs.css | 1 + html/test__docs_8h.html | 147 + html/test__docs_8h.js | 4 + html/test__docs_8h_source.html | 145 + latex/Makefile | 42 + latex/annotated.tex | 4 + latex/classtest_space_1_1test__docs.tex | 44 + latex/doxygen.sty | 714 +++++ latex/etoc_doxygen.sty | 2178 ++++++++++++++ latex/files.tex | 4 + latex/longtable_doxygen.sty | 459 +++ latex/make.bat | 67 + latex/namespaces.tex | 4 + latex/namespacetest_space.tex | 13 + latex/refman.tex | 257 ++ latex/tabu_doxygen.sty | 2557 +++++++++++++++++ latex/test__docs_8h.tex | 37 + latex/test__docs_8h_source.tex | 26 + mkdocs.yml | 21 +- requirements.txt | 3 + 120 files changed, 14450 insertions(+), 43 deletions(-) create mode 100644 Doxyfile_api create mode 100644 Sphinx/Makefile create mode 100644 Sphinx/make.bat create mode 100644 Sphinx/source/conf.py create mode 100644 Sphinx/source/generate_sphinx_dyn.py create mode 100644 Sphinx/source/index.rst delete mode 100644 assets/extra.css create mode 100644 build_docs.ps1 create mode 100644 build_docs.sh create mode 100644 docs/Documentation/docs_home.md create mode 100644 docs/Documentation/engine3d_api_docs.md create mode 100644 docs/Documentation/engine3d_older_doc_list.md create mode 100644 docs/assets/CSS/extra_style.css create mode 100644 docs/assets/CSS/sphinx_api.css create mode 100644 docs/assets/JS/custome-nav.js create mode 100644 docs/assets/JS/dynamic-sidebar.js create mode 100644 docs/assets/JS/sphinx-mkdocs-converter.js rename {assets => docs/assets}/logos/engine3DHighResLogo.png (100%) rename {assets => docs/assets}/logos/engine3dTransparentLogo.png (100%) create mode 100644 engine3d_website_test/Test1_folder/example2_folder/camera.hpp create mode 100644 engine3d_website_test/Test1_folder/math_utils.hpp create mode 100644 engine3d_website_test/string_utils.h create mode 100644 html/annotated.html create mode 100644 html/annotated_dup.js create mode 100644 html/bc_s.png create mode 100644 html/bc_sd.png create mode 100644 html/classes.html create mode 100644 html/classtest_space_1_1test__docs-members.html create mode 100644 html/classtest_space_1_1test__docs.html create mode 100644 html/classtest_space_1_1test__docs.js create mode 100644 html/clipboard.js create mode 100644 html/closed.png create mode 100644 html/cookie.js create mode 100644 html/dir_6bdf1cba9e98d2cc2b433b0ad246f0f0.html create mode 100644 html/dir_6bdf1cba9e98d2cc2b433b0ad246f0f0.js create mode 100644 html/doc.svg create mode 100644 html/docd.svg create mode 100644 html/doxygen.css create mode 100644 html/doxygen.svg create mode 100644 html/doxygen_crawl.html create mode 100644 html/dynsections.js create mode 100644 html/files.html create mode 100644 html/files_dup.js create mode 100644 html/folderclosed.svg create mode 100644 html/folderclosedd.svg create mode 100644 html/folderopen.svg create mode 100644 html/folderopend.svg create mode 100644 html/functions.html create mode 100644 html/functions_func.html create mode 100644 html/index.html create mode 100644 html/jquery.js create mode 100644 html/minus.svg create mode 100644 html/minusd.svg create mode 100644 html/namespaces.html create mode 100644 html/namespaces_dup.js create mode 100644 html/namespacetest_space.html create mode 100644 html/namespacetest_space.js create mode 100644 html/nav_f.png create mode 100644 html/nav_fd.png create mode 100644 html/nav_g.png create mode 100644 html/nav_h.png create mode 100644 html/nav_hd.png create mode 100644 html/navtree.css create mode 100644 html/navtree.js create mode 100644 html/navtreedata.js create mode 100644 html/navtreeindex0.js create mode 100644 html/open.png create mode 100644 html/plus.svg create mode 100644 html/plusd.svg create mode 100644 html/resize.js create mode 100644 html/search/all_0.js create mode 100644 html/search/classes_0.js create mode 100644 html/search/close.svg create mode 100644 html/search/files_0.js create mode 100644 html/search/functions_0.js create mode 100644 html/search/mag.svg create mode 100644 html/search/mag_d.svg create mode 100644 html/search/mag_sel.svg create mode 100644 html/search/mag_seld.svg create mode 100644 html/search/namespaces_0.js create mode 100644 html/search/search.css create mode 100644 html/search/search.js create mode 100644 html/search/searchdata.js create mode 100644 html/splitbar.png create mode 100644 html/splitbard.png create mode 100644 html/sync_off.png create mode 100644 html/sync_on.png create mode 100644 html/tab_a.png create mode 100644 html/tab_ad.png create mode 100644 html/tab_b.png create mode 100644 html/tab_bd.png create mode 100644 html/tab_h.png create mode 100644 html/tab_hd.png create mode 100644 html/tab_s.png create mode 100644 html/tab_sd.png create mode 100644 html/tabs.css create mode 100644 html/test__docs_8h.html create mode 100644 html/test__docs_8h.js create mode 100644 html/test__docs_8h_source.html create mode 100644 latex/Makefile create mode 100644 latex/annotated.tex create mode 100644 latex/classtest_space_1_1test__docs.tex create mode 100644 latex/doxygen.sty create mode 100644 latex/etoc_doxygen.sty create mode 100644 latex/files.tex create mode 100644 latex/longtable_doxygen.sty create mode 100644 latex/make.bat create mode 100644 latex/namespaces.tex create mode 100644 latex/namespacetest_space.tex create mode 100644 latex/refman.tex create mode 100644 latex/tabu_doxygen.sty create mode 100644 latex/test__docs_8h.tex create mode 100644 latex/test__docs_8h_source.tex diff --git a/.gitignore b/.gitignore index 5d6102ec..712e94d2 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,13 @@ venv/ .DS_Store .cache/ + +#Sphinx Data +docs/Documentation/API_Release/ +Sphinx/source/engine3d_website_test/ + +#doxygen +doxygen_output/ + +#Website Output +site/ \ No newline at end of file diff --git a/Doxyfile_api b/Doxyfile_api new file mode 100644 index 00000000..89c6a3a0 --- /dev/null +++ b/Doxyfile_api @@ -0,0 +1,21 @@ +PROJECT_NAME = "Engine3D" +INPUT = {{INPUT_PATH}} +FILE_PATTERNS = *.h* +EXTRACT_STATIC = YES +EXCLUDE_PATTERNS = */third_party/* +HAVE_DOT = YES +OUTPUT_DIRECTORY = ./doxygen_output +XML_OUTPUT = xml +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +GENERATE_HTML = NO +GENERATE_XML = YES +RECURSIVE = YES +QUIET = YES +PREDEFINED = IN_DOXYGEN +EXCLUDE_SYMBOLS = detail +GENERATE_TREEVIEW = YES +SOURCE_BROWSER = YES +WARN_IF_UNDOCUMENTED = YES \ No newline at end of file diff --git a/README.md b/README.md index 391badf0..1eb1a345 100644 --- a/README.md +++ b/README.md @@ -13,3 +13,26 @@ Check https://sfsu-dev.github.io/engine3d.github.io to learn mode. ## Pip Install * Installing the dependencies for this project. `pip install -r requirements.txt` + + +# Doxygen-Breath-Sphinx +* cd into Sphinx/source folder `cd Sphinx\source` +* run `python generate_sphinx_dyn.py` +* run `sphinx-build -b html ./ ../../docs/Documentation/API_Release` +* go back to top folder `cd ../..` + +# Shortcuts + +## Windows +* Run `build_docs.ps1` + +> ⚠️ **Note**: The `build_docs.ps1` script must be executed using PowerShell. +> Attempting to run it in Command Prompt or other shells may result in errors. To execute the script: +> 1. Open PowerShell. +> 2. Navigate to the project directory. +> 3. Run the command: `.\build_docs.ps1` +> 4. the path depends on what your trying to do but it should be absolute + + +# Run mkdocs +* run `mkdocs serve` \ No newline at end of file diff --git a/Sphinx/Makefile b/Sphinx/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/Sphinx/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/Sphinx/make.bat b/Sphinx/make.bat new file mode 100644 index 00000000..dc1312ab --- /dev/null +++ b/Sphinx/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/Sphinx/source/conf.py b/Sphinx/source/conf.py new file mode 100644 index 00000000..15167e3e --- /dev/null +++ b/Sphinx/source/conf.py @@ -0,0 +1,35 @@ +import os +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['breathe'] + +templates_path = ['_templates'] +exclude_patterns = [] + +language = 'en' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] + +# Configure Breathe for Doxygen + +breathe_projects = { + "Engine3D": os.path.abspath("../../doxygen_output/xml") +} +breathe_default_project = "Engine3D" + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +copyright = '2025, Apache 2.0' +author = 'Engine3D Developers' +release = '0.0.1a' diff --git a/Sphinx/source/generate_sphinx_dyn.py b/Sphinx/source/generate_sphinx_dyn.py new file mode 100644 index 00000000..6987ef85 --- /dev/null +++ b/Sphinx/source/generate_sphinx_dyn.py @@ -0,0 +1,107 @@ +import os +import xml.etree.ElementTree as ET +from collections import defaultdict + + +def parse_doxygen_xml_folder(xml_folder, output_dir): + # Build a global hierarchy dictionary + global_hierarchy = defaultdict(dict) + + # Iterate over all files in the XML folder that match *_8h.xml or *_8hpp.xml + for xml_file in os.listdir(xml_folder): + if xml_file.endswith("_8h.xml") or xml_file.endswith("_8hpp.xml"): + xml_path = os.path.join(xml_folder, xml_file) + parse_doxygen_xml(xml_path, global_hierarchy) + + # Generate the .rst files after processing all files + generate_rst(global_hierarchy, output_dir) + + # Generate the root index.rst file + generate_root_index(global_hierarchy, output_dir) + + +def parse_doxygen_xml(xml_path, global_hierarchy): + # Parse the Doxygen XML + tree = ET.parse(xml_path) + root = tree.getroot() + + # Look specifically for the node with id="1" + node = root.find(".//node[@id='1']") + if node is None: + print(f"No node with id=1 found in {xml_path}") + return + + # Find the label in the node + label = node.find("label") + if label is None or not label.text: + print(f"No