Merge branch 'master' into mpl2-boundary

.github/workflows/github-actions-docs-test.yml

@@ -0,0 +1,34 @@
+name: Docs Tester
+
+on:
+  push:
+
+jobs:
+  docs-test-job:
+    name: 'Test docs for Tcl syntax and README'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+      with:
+        submodules: true
+
+    - name: Install required package
+      run: |
+        sudo apt-get update && sudo apt-get install -y pandoc
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'  
+
+    - name: Preprocess files
+      run: |
+        cd docs && make preprocess -j${nproc}
+    - name: Run Tcl syntax parser
+      run: |
+        python3 docs/src/test/man_tcl_params.py
+    - name: Run readme parser
+      run : |
+        cd docs && make clean
+        python3 src/test/readme_check.py

CMakeLists.txt

@@ -153,3 +153,27 @@ if(ENABLE_TESTS)
 endif()
 
 add_subdirectory(src)
+
+
+####################################################################
+
+# Build man pages (Optional)
+
+# Use the processor_count command to get the number of cores
+include(ProcessorCount)
+ProcessorCount(PROCESSOR_COUNT)
+message("Number of processor cores: ${PROCESSOR_COUNT}")
+
+option(BUILD_MAN "Enable building man pages" OFF)
+if(BUILD_MAN)
+  add_custom_target(
+    man_page ALL
+    COMMAND make clean && make preprocess && make all -j${PROCESSOR_COUNT}
+    WORKING_DIRECTORY ${OPENROAD_HOME}/docs
+  )
+
+  # Based on ${CMAKE_INSTALL_PREFIX}, we want to go to ${CMAKE_INSTALL_PREFIX}/share/man
+  set(MANPAGE_DIR ${OPENROAD_HOME}/docs/cat)
+  install(DIRECTORY ${MANPAGE_DIR} DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man)
+
+endif()

docs/.gitignore

@@ -0,0 +1,10 @@
+# dont save intermediate results
+md/man2/*md
+md/man3/*md
+html
+man
+cat
+
+
+# for doc tests
+src/test/results

docs/Makefile

@@ -1,29 +1,164 @@
-# Minimal makefile for Sphinx documentation
-#
+# Makefile is divided into two parts:
+# Pandoc compilation - Manpages
+# Sphinx compilation - ReadTheDocs
+
+#  _____        _   _ _____   ____   _____ 
+# |  __ \ /\   | \ | |  __ \ / __ \ / ____|
+# | |__) /  \  |  \| | |  | | |  | | |     
+# |  ___/ /\ \ | . ` | |  | | |  | | |     
+# | |  / ____ \| |\  | |__| | |__| | |____ 
+# |_| /_/    \_\_| \_|_____/ \____/ \_____|
+
+# Define variables
+PANDOC = pandoc
+NROFF = nroff
+SRC_DIR = md
+MAN_ROOT_DIR = man
+HTML_ROOT_DIR = html
+CAT_ROOT_DIR = cat
+MAN1 = man1
+MAN2 = man2
+MAN3 = man3
+
+# Exclude these set of keywords
+EXCLUDE_KEYWORDS = ant cts dft dpl drt fin gpl grt gui ifp mpl \
+				   mpl2 odb pad par pdn ppl psm rcx rmp rsz sta \
+				   stt tap upf utl
+EXCLUDE_FILES := $(addsuffix .md,$(EXCLUDE_KEYWORDS))
+
+MAN1_DIR = $(MAN_ROOT_DIR)/$(MAN1)
+SRC1_DIR = $(SRC_DIR)/$(MAN1)
+MAN1_FILES = $(wildcard $(SRC1_DIR)/*.md)
+MAN1_PAGES = $(patsubst $(SRC1_DIR)/%.md,$(MAN1_DIR)/%.1,$(MAN1_FILES))
+HTML1_DIR = $(HTML_ROOT_DIR)/html1
+HTML1_PAGES = $(patsubst $(SRC1_DIR)/%.md,$(HTML1_DIR)/%.html,$(MAN1_FILES))
+CAT1_DIR = $(CAT_ROOT_DIR)/cat1
+CAT1_PAGES = $(patsubst $(SRC1_DIR)/%.md,$(CAT1_DIR)/%.1,$(MAN1_FILES))
+
+MAN2_DIR = $(MAN_ROOT_DIR)/$(MAN2)
+SRC2_DIR = $(SRC_DIR)/$(MAN2)
+MAN2_FILES = $(wildcard $(SRC2_DIR)/*.md)
+MAN2_FILES := $(filter-out $(foreach keyword, $(EXCLUDE_FILES), %$(keyword)), $(MAN2_FILES))
+MAN2_PAGES = $(patsubst $(SRC2_DIR)/%.md,$(MAN2_DIR)/%.2,$(MAN2_FILES))
+HTML2_DIR = $(HTML_ROOT_DIR)/html2
+HTML2_PAGES = $(patsubst $(SRC2_DIR)/%.md,$(HTML2_DIR)/%.html,$(MAN2_FILES))
+CAT2_DIR = $(CAT_ROOT_DIR)/cat2
+CAT2_PAGES = $(patsubst $(SRC2_DIR)/%.md,$(CAT2_DIR)/%.2,$(MAN2_FILES))
+
+MAN3_DIR = $(MAN_ROOT_DIR)/$(MAN3)
+SRC3_DIR = $(SRC_DIR)/$(MAN3)
+MAN3_FILES = $(wildcard $(SRC3_DIR)/*.md)
+MAN3_PAGES = $(patsubst $(SRC3_DIR)/%.md,$(MAN3_DIR)/%.3,$(MAN3_FILES))
+HTML3_DIR = $(HTML_ROOT_DIR)/html3
+HTML3_PAGES = $(patsubst $(SRC3_DIR)/%.md,$(HTML3_DIR)/%.html,$(MAN3_FILES))
+CAT3_DIR = $(CAT_ROOT_DIR)/cat3
+CAT3_PAGES = $(patsubst $(SRC3_DIR)/%.md,$(CAT3_DIR)/%.3,$(MAN3_FILES))
+
+# Default target
+all: doc web cat
+
+# Target to do symlinks and pandoc-compatible conversion
+preprocess:
+	./src/scripts/link_readmes.sh && python3 src/scripts/md_roff_compat.py
+
+# Target to generate all man pages
+doc: $(MAN1_PAGES) $(MAN2_PAGES) $(MAN3_PAGES)
+
+# Target to generate all web pages (changed name to disambiguate from sphinx)
+web: $(HTML1_PAGES) $(HTML2_PAGES) $(HTML3_PAGES) 
+
+# Target to generate all cat pages
+cat: $(CAT1_PAGES) $(CAT2_PAGES) $(CAT3_PAGES)
+	@echo $(CAT1_PAGES)
+
+# Rule to create the man directory
+$(MAN1_DIR): 
+	mkdir -p $(MAN1_DIR) 
+$(MAN2_DIR): 
+	mkdir -p $(MAN2_DIR) 
+$(MAN3_DIR): 
+	mkdir -p $(MAN3_DIR) 
+$(HTML1_DIR): 
+	mkdir -p $(HTML1_DIR)
+$(HTML2_DIR): 
+	mkdir -p $(HTML2_DIR)
+$(HTML3_DIR): 
+	mkdir -p $(HTML3_DIR)
+$(CAT1_DIR): 
+	mkdir -p $(CAT1_DIR)
+$(CAT2_DIR): 
+	mkdir -p $(CAT2_DIR)
+$(CAT3_DIR): 
+	mkdir -p $(CAT3_DIR)
+
+# Rule to generate a roff file from a corresponding Markdown file
+$(MAN1_DIR)/%.1: $(SRC1_DIR)/%.md | $(MAN1_DIR)
+	$(PANDOC) -s -t man $< -o $@ --quiet
+$(MAN2_DIR)/%.2: $(SRC2_DIR)/%.md | $(MAN2_DIR)
+	$(PANDOC) -s -t man $< -o $@ --quiet
+$(MAN3_DIR)/%.3: $(SRC3_DIR)/%.md | $(MAN3_DIR)
+	$(PANDOC) -s -t man $< -o $@ --quiet
+
+# Rule to generate a html file from a corresponding roff file
+$(HTML1_DIR)/%.html: $(MAN1_DIR)/%.1 | $(HTML1_DIR)
+	$(PANDOC) -s -o html $< -o $@ --quiet
+$(HTML2_DIR)/%.html: $(MAN2_DIR)/%.2 | $(HTML2_DIR)
+	$(PANDOC) -s -o html $< -o $@ --quiet
+$(HTML3_DIR)/%.html: $(MAN3_DIR)/%.3 | $(HTML3_DIR)
+	$(PANDOC) -s -o html $< -o $@ --quiet
+
+# Rule to generate a cat file from a corresponding roff file
+$(CAT1_DIR)/%.md: $(MAN1_DIR)/%.1 | $(CAT1_DIR)
+	nroff -man $< | col -b > $@
+$(CAT2_DIR)/%.md: $(MAN2_DIR)/%.2 | $(CAT2_DIR)
+	nroff -man $< | col -b > $@
+$(CAT3_DIR)/%.md: $(MAN3_DIR)/%.3 | $(CAT3_DIR)
+	nroff -man $< | col -b > $@
+#$(PANDOC) -s -o markdown $< -o $@
+#sed -i 's/\\\[/\[/g; s/\\]/\]/g; s/\\_/_/g' $@
+
+$(CAT1_DIR)/%.1: $(CAT1_DIR)/%.md
+	mv $< $@
+$(CAT2_DIR)/%.2: $(CAT2_DIR)/%.md
+	mv $< $@
+$(CAT3_DIR)/%.3: $(CAT3_DIR)/%.md
+	mv $< $@
+
+# Phony targets
+.PHONY: all 
+
+#   _____ _____  _    _ _____ _   ___   __
+#  / ____|  __ \| |  | |_   _| \ | \ \ / /
+# | (___ | |__) | |__| | | | |  \| |\ V / 
+#  \___ \|  ___/|  __  | | | | . ` | > <  
+#  ____) | |    | |  | |_| |_| |\  |/ . \ 
+# |_____/|_|    |_|  |_|_____|_| \_/_/ \_\
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     =
 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)
+html: Makefile
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	rm -f main
 	./revert-links.py
-	
+
 checklinks:
 	$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) || echo
 	@echo
 	@echo "Check finished. Report is in $(BUILDDIR)."
 	rm -f main
 	./revert-links.py
+
+# Clean target to remove all man pages/Sphinx docs
+clean:
+	rm -rf $(MAN1_DIR) $(MAN2_DIR) $(MAN3_DIR)
+	rm -rf $(HTML1_DIR) $(HTML2_DIR) $(HTML3_DIR)
+	rm -rf $(CAT1_DIR) $(CAT2_DIR) $(CAT3_DIR)
+	rm -rf ./md/man2/*md
+	rm -rf ./md/man3/*md
+	rm -rf $(BUILDDIR)

docs/README.md

@@ -1,29 +1,52 @@
 # OpenROAD Documentation
 
-This documentation is available at [https://openroad.readthedocs.io/en/latest/](https://openroad.readthedocs.io/en/latest/)
+This `docs/` hierarchy houses code and raw files to 
+build the on-line documentation (using Sphinx) and 
+manual pages using (using Pandoc)
 
-## Build locally
+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`
+## Prerequisites
 
-### Install 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`.
 
-``` 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.
+make preprocess && make all -j16
+```
+
+#### To view manpages
+
+- To run `man` commands inside OpenROAD, you can either use the Linux `man` binary:
+```tcl
+# create a man wrapper
+source man/scripts/main.tcl
+man openroad
 ```
 
-### Build:
+- Or just within OpenROAD itself.
+```tcl
+# you will be prompted to enter the RELATIVE path to cat folders which is optional.
+man openroad
+```
+
+### Build instructions for Sphinx docs
+
+#### HTML docs
 
 ``` shell
 make html
 ```
 
-### Check for broken links:
+#### Check for broken links
 
 ``` shell
 make checklinks

docs/conf.py

@@ -80,6 +80,10 @@
     'main/src/odb/src/def/doc/README.md',
     'main/src/odb/src/lef/README.md',
     'main/docs',
+    'md',  # manpage dir
+    'man', # manpage dir
+    'cat', # manpage dir
+    'html' # manpage dir
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

docs/contrib/DeveloperGuide.md

@@ -134,6 +134,13 @@ examples. Use swig to define internal functions to C++ functionality.
 Tcl files can be included by encoding them in CMake into a string that
 is evaluated at run time (See [`Resizer::init()`](../main/src/rsz/src/Resizer.cc)).
 
+:::{Note}
+Please refer to the top-level Tcl formatting [guide](TclFormat.md).
+Our top-level Tcl files, in particular, have to be formatted in this specific
+manner because of the automatic parsing used to convert the READMEs into
+manpages.
+:::
+
 ## Errors
 
 Tools should report errors to the user using the `ord::error` function
@@ -234,6 +241,13 @@ toolize [-key1 key1] [-flag1] positional_argument1
 Tool commands should be documented in the top-level OpenROAD `README.md`
 file. Detailed documentation should be the `tool/README.md` file.
 
+:::{Note}
+Please refer to the README formatting [guide](ReadmeFormat.md).
+Our top-level READMEs, in particular, have to be formatted in this specific
+manner because of the automatic parsing used to convert the READMEs into
+manpages. 
+:::
+
 ## Tool Flow Namespace
 
 Tool namespaces are usually three-lettered lowercase letters. 
@@ -291,6 +305,7 @@ dependencies make this vastly more complicated.
 1. `regression` script should only write files in a directory that is in the tool's `.gitignore` so the hierarchy does not have modified files in it as a result or running the regressions.
 1. Regressions report no memory errors with `valgrind` (stretch goal).
 1. Regressions report no memory leaks with `valgrind` (difficult).
+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: