From 2b286078064575dc1f78abbe809bfc5f5d7403cc Mon Sep 17 00:00:00 2001 From: Song Luar Date: Mon, 21 Oct 2024 20:28:52 +0800 Subject: [PATCH] Add Doxygen to docs (#4059) * Add Doxygen to docs Signed-off-by: luarss --- .readthedocs.yaml | 1 + Doxyfile | 21 ++++++++++++++++++++ docs/README.md | 18 ++++++++++++++++- docs/conf.py | 13 ++++++------- docs/contrib/DeveloperGuide.md | 35 ++++++++++++++++++++++++++++++++++ docs/doxymain.md | 9 +++++++++ 6 files changed, 89 insertions(+), 8 deletions(-) create mode 100644 Doxyfile create mode 100644 docs/doxymain.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 34720035939..4b7d9ab1e74 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,6 +9,7 @@ build: os: ubuntu-22.04 apt_packages: - libasound2 + - graphviz tools: python: "3.7" nodejs: "16" diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000000..253e7682fac --- /dev/null +++ b/Doxyfile @@ -0,0 +1,21 @@ +PROJECT_NAME = "OpenROAD's Doxygen Pages" +PROJECT_BRIEF = "Compilation of detailed documentation for OpenROAD modules" +PROJECT_LOGO = "" +OUTPUT_DIRECTORY = "./_readthedocs/html/doxygen_output" +DISTRIBUTE_GROUP_DOC = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_PACKAGE = YES +EXTRACT_STATIC = YES +EXTRACT_ANON_NSPACES = YES +INPUT = ./src/odb/include/odb/db.h ./docs/doxymain.md +RECURSIVE = NO +EXCLUDE = README.md +USE_MDFILE_AS_MAINPAGE = ./docs/doxymain.md +SOURCE_BROWSER = YES +INLINE_SOURCES = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = NO +GENERATE_HTML = YES +HAVE_DOT = YES diff --git a/docs/README.md b/docs/README.md index df7c7e05437..7e75b0e6b2b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,17 +6,33 @@ manual pages using (using Pandoc) This on-line documentation is available at [https://openroad.readthedocs.io/en/latest/](https://openroad.readthedocs.io/en/latest/). +### Requires: +- Python 3.x +- Pip +- `virtualenv` +- `doxygen` + ## Prerequisites - To install pandoc, refer to this [link](https://github.com/jgm/pandoc/blob/main/INSTALL.md). `apt-get` *should* just work for Ubuntu. - To install sphinx requirements, **create a virtual environment (e.g. conda/virtualenv)** and then run `pip install -r requirements.txt`. +You may install Doxygen from this [link](https://www.doxygen.nl/download.html). +Most methods of installation are fine, just ensure that `doxygen` is in $PATH. +This is needed for Doxygen compilation. + +To install Python packages: + +``` shell +virtualenv .venv +source .venv/bin/activate +pip install -r requirements.txt + ### Build instructions for Pandoc manpages The `-j16` command is optional for speeding up the manpage compilation process by using multiple jobs based on the number of cores in your system. -```shell make clean # Note this step is important as it regenerates the documentation using latest sources. diff --git a/docs/conf.py b/docs/conf.py index c52067dacd7..c7290e218ed 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,8 +59,7 @@ # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -# source_suffix = ['.rst', '.md'] -source_suffix = [".md"] +source_suffix = [".rst", ".md"] # The master toctree document. master_doc = "index" @@ -152,11 +151,6 @@ ], } -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - def swap_prefix(file, old, new): with open(file, "r") as f: @@ -186,3 +180,8 @@ def setup(app): # for populating OR Messages page. command = "python getMessages.py" _ = os.popen(command).read() + + if not os.path.exists("../_readthedocs/html/doxygen_output"): + os.makedirs("../_readthedocs/html/doxygen_output", exist_ok=True) + command = "cd .. ; doxygen" + _ = os.popen(command).read() diff --git a/docs/contrib/DeveloperGuide.md b/docs/contrib/DeveloperGuide.md index 44699025d51..d5aa129d921 100644 --- a/docs/contrib/DeveloperGuide.md +++ b/docs/contrib/DeveloperGuide.md @@ -308,6 +308,7 @@ dependencies make this vastly more complicated. 1. Ensure the top-level README and Tcl format are compliant. ## Code Linting and Formatting + OpenROAD uses both `clang-tidy` and `clang-format` to perform automatic linting and formatting whenever a pull request is submitted. To run these locally, please first setup Clang Tooling using this [guide](https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html). Thereafter, you may run these commands: ```shell @@ -317,6 +318,40 @@ clang-tidy -p ./build source_file.cpp clang-format -i -style=file:.clang-format source_file.cpp ``` +## Doxygen + +OpenROAD uses Doxygen style comments to generate documentation. +See the generated documentation here. +Our preferred syntax for Doxygen comments can be found in this +[file](../../src/odb/include/odb/odb.h). Also, do refer to the official Doxygen +documentation for more information on what you can include in your Doxygen +comments [here](https://www.doxygen.nl/manual/docblocks.html). + +Below shows an example snippet taken from `./src/odb/include/odb/db.h`: + +```cpp +/// +/// dbProperty - Int property. +/// +class dbIntProperty : public dbProperty +{ + public: + /// Get the value of this property. + int getValue(); + + /// Set the value of this property. + void setValue(int value); + + /// Create a int property. Returns nullptr if a property with the same name + /// already exists. + static dbIntProperty* create(dbObject* object, const char* name, int value); + + /// Find the named property of type int. Returns nullptr if the property does + /// not exist. + static dbIntProperty* find(dbObject* object, const char* name); +}; +``` + ## Guidelines 1. Internally, the code should use `int` for all database units and `int64_t` diff --git a/docs/doxymain.md b/docs/doxymain.md new file mode 100644 index 00000000000..c0be9b86f00 --- /dev/null +++ b/docs/doxymain.md @@ -0,0 +1,9 @@ +# OpenROAD Doxygen Documentation + +To navigate the documentation, the most helpful page would be the class index page. +There you can find individual classes categorized in alphabetical order. + +Alternatively, you may also use the search bar on the top-right hand corner +to find your desired class efficiently. + +To go back to OpenROAD documentation, follow this [link](../../index.html).