Skip to content

Commit 8503851

Browse files
habibayassinhabibayassin
authored
Add documentation from OR repo (#673)
Add docs from OR repo
1 parent 0572f51 commit 8503851

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

74 files changed

+4042
-0
lines changed

‎docs/Makefile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR =
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
rm -f main
22+
23+
checklinks:
24+
$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
25+
@echo
26+
@echo "Check finished. Report is in $(BUILDDIR)."
27+
rm -f main

‎docs/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# OpenROAD Documentation
2+
3+
This documentation is available at [https://openroad.readthedocs.io/en/latest/](https://openroad.readthedocs.io/en/latest/)
4+
5+
## Build locally
6+
7+
### Requires:
8+
- Python 3.x
9+
- Pip
10+
- `virtualenv`
11+
12+
### Install prerequisites:
13+
14+
``` shell
15+
virtualenv .venv
16+
source .venv/bin/activate
17+
pip install -r requirements.txt
18+
```
19+
20+
### Build:
21+
22+
``` shell
23+
make html
24+
```
25+
26+
### Check for broken links:
27+
28+
``` shell
29+
make checklinks
30+
```

‎docs/conf.py‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
import docutils
14+
import os
15+
import re
16+
17+
# -- Project information -----------------------------------------------------
18+
19+
project = 'OpenROAD'
20+
copyright = 'The Regents of the University of California, 2021'
21+
author = 'OpenROAD Team'
22+
23+
24+
# -- General configuration ---------------------------------------------------
25+
26+
# Add any Sphinx extension module names here, as strings. They can be
27+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
28+
# ones.
29+
extensions = [
30+
'sphinx.ext.autodoc',
31+
'sphinx.ext.ifconfig',
32+
'sphinx.ext.mathjax',
33+
'sphinx.ext.napoleon',
34+
'sphinx.ext.todo',
35+
'sphinx_external_toc',
36+
'myst_parser',
37+
]
38+
39+
myst_enable_extensions = [
40+
'amsmath',
41+
'colon_fence',
42+
'deflist',
43+
'dollarmath',
44+
'html_admonition',
45+
'html_image',
46+
'replacements',
47+
'smartquotes',
48+
'substitution',
49+
'tasklist',
50+
'html_image',
51+
]
52+
53+
external_toc_path = 'toc.yml'
54+
55+
# Add any paths that contain templates here, relative to this directory.
56+
templates_path = ['_templates']
57+
58+
# The suffix(es) of source filenames.
59+
# You can specify multiple suffix as a list of string:
60+
#
61+
# source_suffix = ['.rst', '.md']
62+
source_suffix = ['.md']
63+
64+
# The master toctree document.
65+
master_doc = 'index'
66+
67+
# List of patterns, relative to source directory, that match files and
68+
# directories to ignore when looking for source files.
69+
# This pattern also affects html_static_path and html_extra_path.
70+
exclude_patterns = [
71+
'_build',
72+
'Thumbs.db',
73+
'.DS_Store',
74+
'**/LICENSE',
75+
'**/LICENSE.md',
76+
'README.md',
77+
'docs/releases/PostAlpha2.1BranchMethodology.md',
78+
'main/docs',
79+
]
80+
81+
# The name of the Pygments (syntax highlighting) style to use.
82+
pygments_style = None
83+
84+
85+
# -- Options for HTML output -------------------------------------------------
86+
87+
# The theme to use for HTML and HTML Help pages. See the documentation for
88+
# a list of builtin themes.
89+
#
90+
html_theme = "sphinx_symbiflow_theme"
91+
92+
html_theme_options = {
93+
# Specify a list of menu in Header.
94+
# Tuples forms:
95+
# ('Name', 'external url or path of pages in the document', boolean, 'icon name')
96+
#
97+
# Third argument:
98+
# True indicates an external link.
99+
# False indicates path of pages in the document.
100+
#
101+
# Fourth argument:
102+
# Specify the icon name.
103+
# For details see link.
104+
# https://material.io/icons/
105+
'header_links': [
106+
('Home', 'index', False, 'home'),
107+
("The OpenROAD Project", "https://theopenroadproject.org", True, 'launch'),
108+
("GitHub", "https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts", True, 'link')
109+
],
110+
111+
# Customize css colors.
112+
# For details see link.
113+
# https://getmdl.io/customize/index.html
114+
#
115+
# Values: amber, blue, brown, cyan deep_orange, deep_purple, green, grey, indigo, light_blue,
116+
# light_green, lime, orange, pink, purple, red, teal, yellow(Default: indigo)
117+
'primary_color': 'indigo',
118+
# Values: Same as primary_color. (Default: pink)
119+
'accent_color': 'blue',
120+
121+
# Customize layout.
122+
# For details see link.
123+
# https://getmdl.io/components/index.html#layout-section
124+
'fixed_drawer': True,
125+
'fixed_header': True,
126+
'header_waterfall': True,
127+
'header_scroll': False,
128+
129+
# Render title in header.
130+
# Values: True, False (Default: False)
131+
'show_header_title': False,
132+
# Render title in drawer.
133+
# Values: True, False (Default: True)
134+
'show_drawer_title': True,
135+
# Render footer.
136+
# Values: True, False (Default: True)
137+
'show_footer': True,
138+
139+
# Hide the symbiflow links
140+
'hide_symbiflow_links': True,
141+
}
142+
143+
# Add any paths that contain custom static files (such as style sheets) here,
144+
# relative to this directory. They are copied after the builtin static files,
145+
# so a file named "default.css" will overwrite the builtin "default.css".
146+
# html_static_path = ['_static']
147+
148+
def setup(app):
149+
import os
150+
if not os.path.exists('main'):
151+
os.symlink('..', 'main')
152+
prefix = '(../'
153+
newPath = '(./main/'
154+
with open('index.md', 'r') as f:
155+
lines = f.read()
156+
lines = lines.replace(prefix, newPath)
157+
with open('index.md', 'wt') as f:
158+
f.write(lines)

‎docs/contrib/CI.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# CI Guide
2+
3+
This document describes the pipelines available to the developers and code
4+
maintainers in the [Jenkins server](https://jenkins.openroad.tools/). Note
5+
that pipelines with the suffix `*-Private` are only available to code
6+
maintainers and The OpenROAD Project members as they can contain confidential
7+
information. Thus, to access Private pipelines one needs to have authorization
8+
to access confidential data and be logged in the Jenkins website.
9+
10+
Below there is a list of the available features. Instructions on how to
11+
navigate Jenkins to access these features are available
12+
[here](https://docs.google.com/presentation/d/1kWHLjUBFcd0stnDaPNi_pt9WFrrsR7tQ95BGhT1yOvw/edit?usp=sharing).
13+
14+
- Find your build through Jenkins website or from GitHub.
15+
- See test status: Pass/Fail.
16+
- Log files for each test.
17+
- Build artifacts to reproduce failures.
18+
- HTML reports about code coverage and metrics.
19+
20+
## OpenROAD Flow
21+
22+
- OpenROAD-flow-script-Public [folder]
23+
- `public_tests_all`
24+
- Description: runs flow tests except RTLMP designs. Should finish in
25+
less than three hours.
26+
- Target: master branch.
27+
- `public_tests_all-pr`
28+
- Description: runs flow tests except RTLMP designs. Should finish in
29+
less than three hours.
30+
- Target: all open PRs.
31+
- `publish-results-to-dashboard`
32+
- Description: uploads metrics to dashboard website.
33+
- Target: master branch.
34+
- OpenROAD-flow-scripts-Nightly-Public
35+
- Description: runs all flow tests including RTLMP designs.
36+
- Target: master branch.
37+
- OpenROAD-flow-scripts-Private [folder]
38+
- `public_tests_small`
39+
- Description: runs fast flow tests, does not include RTLMP designs.
40+
Should finish in less than one hour.
41+
- Target: all branches that are not filed as PR. CI will run for PR
42+
branches on the public side after "Ready to Sync Public" workflow.
43+
- OpenROAD-flow-scripts-All-Tests-Private
44+
- Description: runs flow tests, does not include RTLMP designs.
45+
- Target: secure branches.

‎docs/contrib/CODE_OF_CONDUCT.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or
31+
advances of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
[email protected].
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series
86+
of actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or
93+
permanent ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within
113+
the community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.0, available at
119+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120+
121+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
122+
enforcement ladder](https://github.com/mozilla/inclusion).
123+
124+
[homepage]: https://www.contributor-covenant.org
125+
126+
For answers to common questions about this code of conduct, see the FAQ at
127+
https://www.contributor-covenant.org/faq. Translations are available at
128+
https://www.contributor-covenant.org/translations.

0 commit comments

Comments
 (0)