Skip to content

Commit 54d3780

Browse files
shoumikchowshoumikchow
committed
Fix makefile, make docs prettier
1 parent 19243ae commit 54d3780

File tree

4 files changed

+165
-22
lines changed

4 files changed

+165
-22
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,8 @@ instance/
6565

6666
# Sphinx documentation
6767
docs/_build/
68+
docs/bbox_visualizer.rst
69+
docs/modules.rst
6870

6971
# PyBuilder
7072
target/

‎Makefile

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: clean clean-test clean-pyc clean-build docs help
1+
.PHONY: clean clean-test clean-pyc clean-build clean-docs docs help
22
.DEFAULT_GOAL := help
33

44
define BROWSER_PYSCRIPT
@@ -26,7 +26,7 @@ BROWSER := python -c "$$BROWSER_PYSCRIPT"
2626
help:
2727
@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
2828

29-
clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
29+
clean: clean-build clean-pyc clean-test clean-docs ## remove all build, test, coverage and Python artifacts
3030

3131
clean-build: ## remove build artifacts
3232
rm -fr build/
@@ -47,21 +47,25 @@ clean-test: ## remove test and coverage artifacts
4747
rm -fr htmlcov/
4848
rm -fr .pytest_cache
4949

50+
clean-docs: ## remove documentation build artifacts
51+
rm -fr docs/_build/
52+
rm -f docs/bbox_visualizer.rst
53+
rm -f docs/modules.rst
54+
5055
lint: ## check style and lint with ruff
5156
uv run ruff check bbox_visualizer tests examples
5257

5358
format: ## format code with ruff
5459
uv run ruff format bbox_visualizer tests examples
5560

5661
test: ## run tests with pytest
57-
uv pip run pytest
62+
uv pip install pytest
63+
uv run pytest
5864

5965
docs: ## generate Sphinx HTML documentation, including API docs
6066
rm -f docs/bbox_visualizer.rst
6167
rm -f docs/modules.rst
6268
sphinx-apidoc -o docs/ bbox_visualizer
63-
rm -f docs/bbox_visualizer.rst
64-
rm -f docs/modules.rst
6569
$(MAKE) -C docs clean
6670
$(MAKE) -C docs html
6771
$(BROWSER) docs/_build/html/index.html
@@ -70,11 +74,13 @@ servedocs: docs ## compile the docs watching for changes
7074
watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
7175

7276
build: clean ## builds source and wheel package
73-
uv pip run python -m build
77+
uv pip install build
78+
uv run python -m build
7479

7580
release: build ## package and upload a release
76-
uv pip run python -m twine check dist/*
77-
uv pip run python -m twine upload dist/*
81+
uv pip install twine
82+
uv run python -m twine check dist/*
83+
uv run python -m twine upload dist/*
7884

7985
install: clean ## install the package to the active Python's site-packages
8086
uv pip install .

‎docs/_static/custom.css

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
/* Custom styles for bbox-visualizer documentation */
2+
3+
/* Make the main content wider */
4+
.wy-nav-content {
5+
max-width: 1000px !important;
6+
}
7+
8+
/* Improve code block appearance */
9+
div[class^="highlight"] pre {
10+
line-height: 1.5;
11+
padding: 12px 15px;
12+
border-radius: 4px;
13+
}
14+
15+
/* Better heading styles */
16+
h1, h2, h3, h4, h5, h6 {
17+
margin-top: 2em;
18+
margin-bottom: 1em;
19+
}
20+
21+
h1 {
22+
padding-bottom: 0.3em;
23+
border-bottom: 1px solid #eaecef;
24+
}
25+
26+
/* Improve table styles */
27+
table.docutils {
28+
border-radius: 4px;
29+
overflow: hidden;
30+
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
31+
}
32+
33+
table.docutils td, table.docutils th {
34+
padding: 8px 12px !important;
35+
}
36+
37+
/* Better admonition (note, warning, etc.) styling */
38+
.admonition {
39+
border-radius: 4px;
40+
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
41+
}
42+
43+
.admonition-title {
44+
padding: 8px 12px !important;
45+
}
46+
47+
/* Improve function/class signature appearance */
48+
dl.py.method, dl.py.function, dl.py.class {
49+
padding: 15px;
50+
margin: 15px 0;
51+
border: 1px solid #e1e4e5;
52+
border-radius: 4px;
53+
background: #f8f9fa;
54+
}
55+
56+
/* Better parameter list styling */
57+
dl.field-list > dt {
58+
padding: 6px 10px;
59+
background: #f0f0f0;
60+
border-radius: 4px;
61+
}
62+
63+
/* Improve navigation sidebar */
64+
.wy-menu-vertical li.current > a {
65+
background: #e3efff !important;
66+
}
67+
68+
.wy-menu-vertical li.current {
69+
background: #f3f6f9;
70+
}
71+
72+
/* Better code signature colors */
73+
.sig-name {
74+
color: #2980b9 !important;
75+
}
76+
77+
.sig-param {
78+
color: #3c3c3c !important;
79+
}
80+
81+
/* Improve search box appearance */
82+
.wy-side-nav-search input[type="text"] {
83+
border-radius: 4px;
84+
box-shadow: none;
85+
border: 1px solid #e1e4e5;
86+
}

‎docs/conf.py

Lines changed: 63 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,20 @@
3636
'sphinx.ext.napoleon',
3737
'sphinx.ext.viewcode',
3838
'sphinx.ext.githubpages',
39+
'sphinx.ext.intersphinx',
40+
'sphinx.ext.autosectionlabel',
3941
'sphinx_autodoc_typehints',
42+
'sphinx.ext.todo',
4043
'myst_parser',
4144
]
4245

46+
# Intersphinx configuration
47+
intersphinx_mapping = {
48+
'python': ('https://docs.python.org/3', None),
49+
'numpy': ('https://numpy.org/doc/stable/', None),
50+
'opencv': ('https://docs.opencv.org/4.x/', None),
51+
}
52+
4353
# Add any paths that contain templates here, relative to this directory.
4454
templates_path = ['_templates']
4555

@@ -54,7 +64,7 @@
5464

5565
# General information about the project.
5666
project = 'bbox-visualizer'
57-
copyright = '2024, Shoumik Sharar Chowdhury'
67+
copyright = '2025, Shoumik Sharar Chowdhury'
5868
author = 'Shoumik Sharar Chowdhury'
5969

6070
# The version info for the project you're documenting, acts as replacement
@@ -82,26 +92,43 @@
8292
pygments_style = 'sphinx'
8393

8494
# If true, `todo` and `todoList` produce output, else they produce nothing.
85-
todo_include_todos = False
95+
todo_include_todos = True
8696

8797

8898
# -- Options for HTML output -------------------------------------------
8999

90-
# The theme to use for HTML and HTML Help pages. See the documentation for
91-
# a list of builtin themes.
92-
#
100+
# The theme to use for HTML and HTML Help pages.
93101
html_theme = 'sphinx_rtd_theme'
94102

95-
# Theme options are theme-specific and customize the look and feel of a
96-
# theme further. For a list of options available for each theme, see the
97-
# documentation.
98-
#
99-
# html_theme_options = {}
103+
# Theme options are theme-specific and customize the look and feel of a theme
104+
html_theme_options = {
105+
'logo_only': False,
106+
'display_version': True,
107+
'prev_next_buttons_location': 'bottom',
108+
'style_external_links': True,
109+
'style_nav_header_background': '#2980B9',
110+
# Toc options
111+
'collapse_navigation': False,
112+
'sticky_navigation': True,
113+
'navigation_depth': 4,
114+
'includehidden': True,
115+
'titles_only': False
116+
}
100117

101-
# Add any paths that contain custom static files (such as style sheets) here,
102-
# relative to this directory. They are copied after the builtin static files,
103-
# so a file named "default.css" will overwrite the builtin "default.css".
118+
# The name of an image file (relative to this directory) to place at the top
119+
# of the sidebar.
120+
# html_logo = "_static/logo.png" # Uncomment and add your logo if you have one
121+
122+
# The name of an image file (within the static path) to use as favicon of the
123+
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
124+
# pixels large.
125+
# html_favicon = "_static/favicon.ico" # Uncomment and add your favicon if you have one
126+
127+
# Add any paths that contain custom static files (such as style sheets) here
104128
html_static_path = ['_static']
129+
html_css_files = [
130+
'custom.css',
131+
]
105132

106133
#
107134
autosectionlabel_prefix_document = True
@@ -176,9 +203,13 @@
176203
'undoc-members': False,
177204
'exclude-members': '__weakref__',
178205
'private-members': False,
179-
'show-inheritance': True
206+
'show-inheritance': True,
207+
'inherited-members': True
180208
}
181209

210+
# Enable todo notes
211+
todo_include_todos = True
212+
182213
# Don't show type hints in the signature - they're already in the parameter list
183214
autodoc_typehints = 'description'
184215

@@ -188,5 +219,23 @@
188219
# Sort members by source order
189220
autodoc_member_order = 'bysource'
190221

222+
# -- Additional settings ---------------------------------------------
223+
# If true, show URLs in the documentation
224+
html_show_sourcelink = True
225+
226+
# -- Napoleon settings ------------------------------------------------
227+
napoleon_google_docstring = True
228+
napoleon_numpy_docstring = True
229+
napoleon_include_init_with_doc = True
230+
napoleon_include_private_with_doc = False
231+
napoleon_include_special_with_doc = True
232+
napoleon_use_admonition_for_examples = True
233+
napoleon_use_admonition_for_notes = True
234+
napoleon_use_admonition_for_references = True
235+
napoleon_use_ivar = True
236+
napoleon_use_param = True
237+
napoleon_use_rtype = True
238+
napoleon_type_aliases = None
239+
191240

192241

0 commit comments

Comments
 (0)