Add Doxygen to docs (#4059)

* Add Doxygen to docs

Signed-off-by: luarss <[email protected]>

.readthedocs.yaml

@@ -9,6 +9,7 @@ build:
   os: ubuntu-22.04
   apt_packages:
     - libasound2
+    - graphviz
   tools:
     python: "3.7"
     nodejs: "16"

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

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.

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()

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 <a href="../doxygen_output/html/index.html">here</a>.
+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`

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).