diff --git a/.gitignore b/.gitignore index 5d6102ec..534af9ed 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,15 @@ venv/ .DS_Store .cache/ + +#Sphinx Data +docs/Documentation/API_Release/ +Sphinx/source/engine3d_website_test/ + +#doxygen +doxygen_output/ + +#Website Output +site/ +html/ +latex/ 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..c02e0e89 100644 --- a/README.md +++ b/README.md @@ -13,3 +13,28 @@ 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 +* running on linux for github to deploy `sudo apt install doxygen` + +# 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