From 3502c4ac68f22dee164311af63c1f671f7fc4dbc Mon Sep 17 00:00:00 2001 From: Alex Rudy Date: Mon, 25 Mar 2024 18:30:50 +0000 Subject: [PATCH] Adds documentation for additional reference topics --- docs/api/bootlace.image.Image.rst | 23 ++++++++++ docs/api/bootlace.links.Link.rst | 21 +++++++++ docs/api/bootlace.links.View.rst | 27 +++++++++++ docs/api/bootlace.nav.NavAlignment.rst | 21 +++++++++ docs/api/bootlace.nav.NavStyle.rst | 23 ++++++++++ docs/api/bootlace.nav.elements.Brand.rst | 17 +++++++ docs/api/bootlace.nav.elements.Dropdown.rst | 19 ++++++++ docs/api/bootlace.nav.elements.Link.rst | 37 +++++++++++++++ docs/api/bootlace.nav.elements.Nav.rst | 21 +++++++++ docs/api/bootlace.nav.elements.NavBar.rst | 25 +++++++++++ .../bootlace.nav.elements.NavBarCollapse.rst | 17 +++++++ docs/api/bootlace.nav.elements.NavBarNav.rst | 17 +++++++ .../bootlace.nav.elements.NavBarSearch.rst | 25 +++++++++++ docs/api/bootlace.nav.elements.Separator.rst | 7 +++ docs/api/bootlace.nav.elements.Text.rst | 19 ++++++++ docs/api/bootlace.size.SizeClass.rst | 37 +++++++++++++++ docs/api/bootlace.style.ColorClass.rst | 45 +++++++++++++++++++ docs/api/bootlace.table.CheckColumn.rst | 29 ++++++++++++ docs/api/bootlace.table.Column.rst | 17 +++++++ docs/api/bootlace.table.ColumnBase.rst | 29 ++++++++++++ docs/api/bootlace.table.Datetime.rst | 17 +++++++ docs/api/bootlace.table.Heading.rst | 19 ++++++++ docs/api/bootlace.table.Table.rst | 29 ++++++++++++ docs/api/bootlace.util.BootlaceWarning.rst | 6 +++ docs/api/bootlace.util.Classes.rst | 21 +++++++++ docs/api/bootlace.util.HtmlIDScope.rst | 29 ++++++++++++ docs/api/bootlace.util.IntoTag.rst | 6 +++ docs/api/bootlace.util.MaybeTaggable.rst | 6 +++ docs/api/bootlace.util.Taggable.rst | 7 +++ docs/api/bootlace.util.as_tag.rst | 6 +++ docs/api/bootlace.util.ids.rst | 6 +++ docs/api/bootlace.util.is_active_endpoint.rst | 6 +++ docs/api/bootlace.util.maybe.rst | 6 +++ docs/api/bootlace.util.render.rst | 6 +++ docs/reference.rst | 6 +++ docs/reference/image.rst | 4 ++ docs/reference/layout.rst | 6 +++ docs/reference/link.rst | 4 ++ docs/reference/nav.rst | 7 +++ docs/reference/table.rst | 5 +++ docs/reference/tools.rst | 5 +++ src/bootlace/image.py | 11 +++++ src/bootlace/links.py | 20 +++++++++ src/bootlace/nav/bar.py | 22 +++++++++ src/bootlace/nav/core.py | 16 +++++++ src/bootlace/nav/nav.py | 12 +++++ src/bootlace/size.py | 14 ++++++ src/bootlace/style.py | 29 ++++++++++-- src/bootlace/table/base.py | 13 ++++++ src/bootlace/table/columns.py | 17 +++++++ src/bootlace/util.py | 27 +++++++++++ 51 files changed, 861 insertions(+), 3 deletions(-) create mode 100644 docs/api/bootlace.image.Image.rst create mode 100644 docs/api/bootlace.links.Link.rst create mode 100644 docs/api/bootlace.links.View.rst create mode 100644 docs/api/bootlace.nav.NavAlignment.rst create mode 100644 docs/api/bootlace.nav.NavStyle.rst create mode 100644 docs/api/bootlace.nav.elements.Brand.rst create mode 100644 docs/api/bootlace.nav.elements.Dropdown.rst create mode 100644 docs/api/bootlace.nav.elements.Link.rst create mode 100644 docs/api/bootlace.nav.elements.Nav.rst create mode 100644 docs/api/bootlace.nav.elements.NavBar.rst create mode 100644 docs/api/bootlace.nav.elements.NavBarCollapse.rst create mode 100644 docs/api/bootlace.nav.elements.NavBarNav.rst create mode 100644 docs/api/bootlace.nav.elements.NavBarSearch.rst create mode 100644 docs/api/bootlace.nav.elements.Separator.rst create mode 100644 docs/api/bootlace.nav.elements.Text.rst create mode 100644 docs/api/bootlace.size.SizeClass.rst create mode 100644 docs/api/bootlace.style.ColorClass.rst create mode 100644 docs/api/bootlace.table.CheckColumn.rst create mode 100644 docs/api/bootlace.table.Column.rst create mode 100644 docs/api/bootlace.table.ColumnBase.rst create mode 100644 docs/api/bootlace.table.Datetime.rst create mode 100644 docs/api/bootlace.table.Heading.rst create mode 100644 docs/api/bootlace.table.Table.rst create mode 100644 docs/api/bootlace.util.BootlaceWarning.rst create mode 100644 docs/api/bootlace.util.Classes.rst create mode 100644 docs/api/bootlace.util.HtmlIDScope.rst create mode 100644 docs/api/bootlace.util.IntoTag.rst create mode 100644 docs/api/bootlace.util.MaybeTaggable.rst create mode 100644 docs/api/bootlace.util.Taggable.rst create mode 100644 docs/api/bootlace.util.as_tag.rst create mode 100644 docs/api/bootlace.util.ids.rst create mode 100644 docs/api/bootlace.util.is_active_endpoint.rst create mode 100644 docs/api/bootlace.util.maybe.rst create mode 100644 docs/api/bootlace.util.render.rst create mode 100644 docs/reference/image.rst create mode 100644 docs/reference/layout.rst create mode 100644 docs/reference/link.rst create mode 100644 docs/reference/nav.rst create mode 100644 docs/reference/table.rst create mode 100644 docs/reference/tools.rst diff --git a/docs/api/bootlace.image.Image.rst b/docs/api/bootlace.image.Image.rst new file mode 100644 index 0000000..3698b97 --- /dev/null +++ b/docs/api/bootlace.image.Image.rst @@ -0,0 +1,23 @@ +Image +===== + +.. currentmodule:: bootlace.image + +.. autoclass:: Image + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Image.alt + ~Image.height + ~Image.src + ~Image.width + + .. rubric:: Attributes Documentation + + .. autoattribute:: alt + .. autoattribute:: height + .. autoattribute:: src + .. autoattribute:: width diff --git a/docs/api/bootlace.links.Link.rst b/docs/api/bootlace.links.Link.rst new file mode 100644 index 0000000..e1763ee --- /dev/null +++ b/docs/api/bootlace.links.Link.rst @@ -0,0 +1,21 @@ +Link +==== + +.. currentmodule:: bootlace.links + +.. autoclass:: Link + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Link.active + ~Link.enabled + ~Link.url + + .. rubric:: Attributes Documentation + + .. autoattribute:: active + .. autoattribute:: enabled + .. autoattribute:: url diff --git a/docs/api/bootlace.links.View.rst b/docs/api/bootlace.links.View.rst new file mode 100644 index 0000000..4b67e15 --- /dev/null +++ b/docs/api/bootlace.links.View.rst @@ -0,0 +1,27 @@ +View +==== + +.. currentmodule:: bootlace.links + +.. autoclass:: View + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~View.active + ~View.enabled + ~View.endpoint + ~View.ignore_query + ~View.url + ~View.url_kwargs + + .. rubric:: Attributes Documentation + + .. autoattribute:: active + .. autoattribute:: enabled + .. autoattribute:: endpoint + .. autoattribute:: ignore_query + .. autoattribute:: url + .. autoattribute:: url_kwargs diff --git a/docs/api/bootlace.nav.NavAlignment.rst b/docs/api/bootlace.nav.NavAlignment.rst new file mode 100644 index 0000000..1dbf9ad --- /dev/null +++ b/docs/api/bootlace.nav.NavAlignment.rst @@ -0,0 +1,21 @@ +NavAlignment +============ + +.. currentmodule:: bootlace.nav + +.. autoclass:: NavAlignment + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~NavAlignment.DEFAULT + ~NavAlignment.FILL + ~NavAlignment.JUSTIFIED + + .. rubric:: Attributes Documentation + + .. autoattribute:: DEFAULT + .. autoattribute:: FILL + .. autoattribute:: JUSTIFIED diff --git a/docs/api/bootlace.nav.NavStyle.rst b/docs/api/bootlace.nav.NavStyle.rst new file mode 100644 index 0000000..d3a5ee5 --- /dev/null +++ b/docs/api/bootlace.nav.NavStyle.rst @@ -0,0 +1,23 @@ +NavStyle +======== + +.. currentmodule:: bootlace.nav + +.. autoclass:: NavStyle + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~NavStyle.PILLS + ~NavStyle.PLAIN + ~NavStyle.TABS + ~NavStyle.UNDERLINE + + .. rubric:: Attributes Documentation + + .. autoattribute:: PILLS + .. autoattribute:: PLAIN + .. autoattribute:: TABS + .. autoattribute:: UNDERLINE diff --git a/docs/api/bootlace.nav.elements.Brand.rst b/docs/api/bootlace.nav.elements.Brand.rst new file mode 100644 index 0000000..09b9ba9 --- /dev/null +++ b/docs/api/bootlace.nav.elements.Brand.rst @@ -0,0 +1,17 @@ +Brand +===== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: Brand + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Brand.id + + .. rubric:: Attributes Documentation + + .. autoattribute:: id diff --git a/docs/api/bootlace.nav.elements.Dropdown.rst b/docs/api/bootlace.nav.elements.Dropdown.rst new file mode 100644 index 0000000..33578d2 --- /dev/null +++ b/docs/api/bootlace.nav.elements.Dropdown.rst @@ -0,0 +1,19 @@ +Dropdown +======== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: Dropdown + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Dropdown.id + ~Dropdown.title + + .. rubric:: Attributes Documentation + + .. autoattribute:: id + .. autoattribute:: title diff --git a/docs/api/bootlace.nav.elements.Link.rst b/docs/api/bootlace.nav.elements.Link.rst new file mode 100644 index 0000000..3d386f1 --- /dev/null +++ b/docs/api/bootlace.nav.elements.Link.rst @@ -0,0 +1,37 @@ +Link +==== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: Link + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Link.active + ~Link.enabled + ~Link.id + ~Link.link + ~Link.url + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Link.with_url + ~Link.with_view + + .. rubric:: Attributes Documentation + + .. autoattribute:: active + .. autoattribute:: enabled + .. autoattribute:: id + .. autoattribute:: link + .. autoattribute:: url + + .. rubric:: Methods Documentation + + .. automethod:: with_url + .. automethod:: with_view diff --git a/docs/api/bootlace.nav.elements.Nav.rst b/docs/api/bootlace.nav.elements.Nav.rst new file mode 100644 index 0000000..2137b9f --- /dev/null +++ b/docs/api/bootlace.nav.elements.Nav.rst @@ -0,0 +1,21 @@ +Nav +=== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: Nav + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Nav.alignment + ~Nav.id + ~Nav.style + + .. rubric:: Attributes Documentation + + .. autoattribute:: alignment + .. autoattribute:: id + .. autoattribute:: style diff --git a/docs/api/bootlace.nav.elements.NavBar.rst b/docs/api/bootlace.nav.elements.NavBar.rst new file mode 100644 index 0000000..e0103b7 --- /dev/null +++ b/docs/api/bootlace.nav.elements.NavBar.rst @@ -0,0 +1,25 @@ +NavBar +====== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: NavBar + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~NavBar.color + ~NavBar.expand + ~NavBar.fluid + ~NavBar.id + ~NavBar.items + + .. rubric:: Attributes Documentation + + .. autoattribute:: color + .. autoattribute:: expand + .. autoattribute:: fluid + .. autoattribute:: id + .. autoattribute:: items diff --git a/docs/api/bootlace.nav.elements.NavBarCollapse.rst b/docs/api/bootlace.nav.elements.NavBarCollapse.rst new file mode 100644 index 0000000..ca19123 --- /dev/null +++ b/docs/api/bootlace.nav.elements.NavBarCollapse.rst @@ -0,0 +1,17 @@ +NavBarCollapse +============== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: NavBarCollapse + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~NavBarCollapse.id + + .. rubric:: Attributes Documentation + + .. autoattribute:: id diff --git a/docs/api/bootlace.nav.elements.NavBarNav.rst b/docs/api/bootlace.nav.elements.NavBarNav.rst new file mode 100644 index 0000000..c175dd1 --- /dev/null +++ b/docs/api/bootlace.nav.elements.NavBarNav.rst @@ -0,0 +1,17 @@ +NavBarNav +========= + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: NavBarNav + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~NavBarNav.id + + .. rubric:: Attributes Documentation + + .. autoattribute:: id diff --git a/docs/api/bootlace.nav.elements.NavBarSearch.rst b/docs/api/bootlace.nav.elements.NavBarSearch.rst new file mode 100644 index 0000000..338df9b --- /dev/null +++ b/docs/api/bootlace.nav.elements.NavBarSearch.rst @@ -0,0 +1,25 @@ +NavBarSearch +============ + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: NavBarSearch + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~NavBarSearch.action + ~NavBarSearch.button + ~NavBarSearch.id + ~NavBarSearch.method + ~NavBarSearch.placeholder + + .. rubric:: Attributes Documentation + + .. autoattribute:: action + .. autoattribute:: button + .. autoattribute:: id + .. autoattribute:: method + .. autoattribute:: placeholder diff --git a/docs/api/bootlace.nav.elements.Separator.rst b/docs/api/bootlace.nav.elements.Separator.rst new file mode 100644 index 0000000..85ae0c1 --- /dev/null +++ b/docs/api/bootlace.nav.elements.Separator.rst @@ -0,0 +1,7 @@ +Separator +========= + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: Separator + :show-inheritance: diff --git a/docs/api/bootlace.nav.elements.Text.rst b/docs/api/bootlace.nav.elements.Text.rst new file mode 100644 index 0000000..1bab6fd --- /dev/null +++ b/docs/api/bootlace.nav.elements.Text.rst @@ -0,0 +1,19 @@ +Text +==== + +.. currentmodule:: bootlace.nav.elements + +.. autoclass:: Text + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Text.enabled + ~Text.text + + .. rubric:: Attributes Documentation + + .. autoattribute:: enabled + .. autoattribute:: text diff --git a/docs/api/bootlace.size.SizeClass.rst b/docs/api/bootlace.size.SizeClass.rst new file mode 100644 index 0000000..7922784 --- /dev/null +++ b/docs/api/bootlace.size.SizeClass.rst @@ -0,0 +1,37 @@ +SizeClass +========= + +.. currentmodule:: bootlace.size + +.. autoclass:: SizeClass + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~SizeClass.EXTRA_EXTRA_LARGE + ~SizeClass.EXTRA_LARGE + ~SizeClass.EXTRA_SMALL + ~SizeClass.LARGE + ~SizeClass.MEDIUM + ~SizeClass.SMALL + + .. rubric:: Methods Summary + + .. autosummary:: + + ~SizeClass.add_to_class + + .. rubric:: Attributes Documentation + + .. autoattribute:: EXTRA_EXTRA_LARGE + .. autoattribute:: EXTRA_LARGE + .. autoattribute:: EXTRA_SMALL + .. autoattribute:: LARGE + .. autoattribute:: MEDIUM + .. autoattribute:: SMALL + + .. rubric:: Methods Documentation + + .. automethod:: add_to_class diff --git a/docs/api/bootlace.style.ColorClass.rst b/docs/api/bootlace.style.ColorClass.rst new file mode 100644 index 0000000..0c5f0bd --- /dev/null +++ b/docs/api/bootlace.style.ColorClass.rst @@ -0,0 +1,45 @@ +ColorClass +========== + +.. currentmodule:: bootlace.style + +.. autoclass:: ColorClass + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~ColorClass.BODY + ~ColorClass.DANGER + ~ColorClass.DARK + ~ColorClass.INFO + ~ColorClass.LIGHT + ~ColorClass.PRIMARY + ~ColorClass.SECONDARY + ~ColorClass.SUCCESS + ~ColorClass.TERTIARY + ~ColorClass.WARNING + + .. rubric:: Methods Summary + + .. autosummary:: + + ~ColorClass.add_to_class + + .. rubric:: Attributes Documentation + + .. autoattribute:: BODY + .. autoattribute:: DANGER + .. autoattribute:: DARK + .. autoattribute:: INFO + .. autoattribute:: LIGHT + .. autoattribute:: PRIMARY + .. autoattribute:: SECONDARY + .. autoattribute:: SUCCESS + .. autoattribute:: TERTIARY + .. autoattribute:: WARNING + + .. rubric:: Methods Documentation + + .. automethod:: add_to_class diff --git a/docs/api/bootlace.table.CheckColumn.rst b/docs/api/bootlace.table.CheckColumn.rst new file mode 100644 index 0000000..288b9e4 --- /dev/null +++ b/docs/api/bootlace.table.CheckColumn.rst @@ -0,0 +1,29 @@ +CheckColumn +=========== + +.. currentmodule:: bootlace.table + +.. autoclass:: CheckColumn + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~CheckColumn.no + ~CheckColumn.yes + + .. rubric:: Methods Summary + + .. autosummary:: + + ~CheckColumn.cell + + .. rubric:: Attributes Documentation + + .. autoattribute:: no + .. autoattribute:: yes + + .. rubric:: Methods Documentation + + .. automethod:: cell diff --git a/docs/api/bootlace.table.Column.rst b/docs/api/bootlace.table.Column.rst new file mode 100644 index 0000000..07ffba5 --- /dev/null +++ b/docs/api/bootlace.table.Column.rst @@ -0,0 +1,17 @@ +Column +====== + +.. currentmodule:: bootlace.table + +.. autoclass:: Column + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Column.cell + + .. rubric:: Methods Documentation + + .. automethod:: cell diff --git a/docs/api/bootlace.table.ColumnBase.rst b/docs/api/bootlace.table.ColumnBase.rst new file mode 100644 index 0000000..1d0d6fa --- /dev/null +++ b/docs/api/bootlace.table.ColumnBase.rst @@ -0,0 +1,29 @@ +ColumnBase +========== + +.. currentmodule:: bootlace.table + +.. autoclass:: ColumnBase + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~ColumnBase.attribute + ~ColumnBase.heading + + .. rubric:: Methods Summary + + .. autosummary:: + + ~ColumnBase.cell + + .. rubric:: Attributes Documentation + + .. autoattribute:: attribute + .. autoattribute:: heading + + .. rubric:: Methods Documentation + + .. automethod:: cell diff --git a/docs/api/bootlace.table.Datetime.rst b/docs/api/bootlace.table.Datetime.rst new file mode 100644 index 0000000..f60c8e2 --- /dev/null +++ b/docs/api/bootlace.table.Datetime.rst @@ -0,0 +1,17 @@ +Datetime +======== + +.. currentmodule:: bootlace.table + +.. autoclass:: Datetime + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Datetime.cell + + .. rubric:: Methods Documentation + + .. automethod:: cell diff --git a/docs/api/bootlace.table.Heading.rst b/docs/api/bootlace.table.Heading.rst new file mode 100644 index 0000000..1d208a2 --- /dev/null +++ b/docs/api/bootlace.table.Heading.rst @@ -0,0 +1,19 @@ +Heading +======= + +.. currentmodule:: bootlace.table + +.. autoclass:: Heading + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Heading.icon + ~Heading.text + + .. rubric:: Attributes Documentation + + .. autoattribute:: icon + .. autoattribute:: text diff --git a/docs/api/bootlace.table.Table.rst b/docs/api/bootlace.table.Table.rst new file mode 100644 index 0000000..e90e7e8 --- /dev/null +++ b/docs/api/bootlace.table.Table.rst @@ -0,0 +1,29 @@ +Table +===== + +.. currentmodule:: bootlace.table + +.. autoclass:: Table + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~Table.columns + ~Table.decorated_classes + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Table.__call__ + + .. rubric:: Attributes Documentation + + .. autoattribute:: columns + .. autoattribute:: decorated_classes + + .. rubric:: Methods Documentation + + .. automethod:: __call__ diff --git a/docs/api/bootlace.util.BootlaceWarning.rst b/docs/api/bootlace.util.BootlaceWarning.rst new file mode 100644 index 0000000..838f726 --- /dev/null +++ b/docs/api/bootlace.util.BootlaceWarning.rst @@ -0,0 +1,6 @@ +BootlaceWarning +=============== + +.. currentmodule:: bootlace.util + +.. autoexception:: BootlaceWarning diff --git a/docs/api/bootlace.util.Classes.rst b/docs/api/bootlace.util.Classes.rst new file mode 100644 index 0000000..94b20ec --- /dev/null +++ b/docs/api/bootlace.util.Classes.rst @@ -0,0 +1,21 @@ +Classes +======= + +.. currentmodule:: bootlace.util + +.. autoclass:: Classes + :show-inheritance: + + .. rubric:: Methods Summary + + .. autosummary:: + + ~Classes.add + ~Classes.remove + ~Classes.swap + + .. rubric:: Methods Documentation + + .. automethod:: add + .. automethod:: remove + .. automethod:: swap diff --git a/docs/api/bootlace.util.HtmlIDScope.rst b/docs/api/bootlace.util.HtmlIDScope.rst new file mode 100644 index 0000000..fc9623e --- /dev/null +++ b/docs/api/bootlace.util.HtmlIDScope.rst @@ -0,0 +1,29 @@ +HtmlIDScope +=========== + +.. currentmodule:: bootlace.util + +.. autoclass:: HtmlIDScope + :show-inheritance: + + .. rubric:: Attributes Summary + + .. autosummary:: + + ~HtmlIDScope.scopes + + .. rubric:: Methods Summary + + .. autosummary:: + + ~HtmlIDScope.__call__ + ~HtmlIDScope.factory + + .. rubric:: Attributes Documentation + + .. autoattribute:: scopes + + .. rubric:: Methods Documentation + + .. automethod:: __call__ + .. automethod:: factory diff --git a/docs/api/bootlace.util.IntoTag.rst b/docs/api/bootlace.util.IntoTag.rst new file mode 100644 index 0000000..875fb8b --- /dev/null +++ b/docs/api/bootlace.util.IntoTag.rst @@ -0,0 +1,6 @@ +IntoTag +======= + +.. currentmodule:: bootlace.util + +.. autodata:: IntoTag diff --git a/docs/api/bootlace.util.MaybeTaggable.rst b/docs/api/bootlace.util.MaybeTaggable.rst new file mode 100644 index 0000000..f7ae05c --- /dev/null +++ b/docs/api/bootlace.util.MaybeTaggable.rst @@ -0,0 +1,6 @@ +MaybeTaggable +============= + +.. currentmodule:: bootlace.util + +.. autodata:: MaybeTaggable diff --git a/docs/api/bootlace.util.Taggable.rst b/docs/api/bootlace.util.Taggable.rst new file mode 100644 index 0000000..f39ee5a --- /dev/null +++ b/docs/api/bootlace.util.Taggable.rst @@ -0,0 +1,7 @@ +Taggable +======== + +.. currentmodule:: bootlace.util + +.. autoclass:: Taggable + :show-inheritance: diff --git a/docs/api/bootlace.util.as_tag.rst b/docs/api/bootlace.util.as_tag.rst new file mode 100644 index 0000000..3b48246 --- /dev/null +++ b/docs/api/bootlace.util.as_tag.rst @@ -0,0 +1,6 @@ +as_tag +====== + +.. currentmodule:: bootlace.util + +.. autofunction:: as_tag diff --git a/docs/api/bootlace.util.ids.rst b/docs/api/bootlace.util.ids.rst new file mode 100644 index 0000000..9c450c7 --- /dev/null +++ b/docs/api/bootlace.util.ids.rst @@ -0,0 +1,6 @@ +ids +=== + +.. currentmodule:: bootlace.util + +.. autodata:: ids diff --git a/docs/api/bootlace.util.is_active_endpoint.rst b/docs/api/bootlace.util.is_active_endpoint.rst new file mode 100644 index 0000000..53b7735 --- /dev/null +++ b/docs/api/bootlace.util.is_active_endpoint.rst @@ -0,0 +1,6 @@ +is_active_endpoint +================== + +.. currentmodule:: bootlace.util + +.. autofunction:: is_active_endpoint diff --git a/docs/api/bootlace.util.maybe.rst b/docs/api/bootlace.util.maybe.rst new file mode 100644 index 0000000..dd84f83 --- /dev/null +++ b/docs/api/bootlace.util.maybe.rst @@ -0,0 +1,6 @@ +maybe +===== + +.. currentmodule:: bootlace.util + +.. autofunction:: maybe diff --git a/docs/api/bootlace.util.render.rst b/docs/api/bootlace.util.render.rst new file mode 100644 index 0000000..4835481 --- /dev/null +++ b/docs/api/bootlace.util.render.rst @@ -0,0 +1,6 @@ +render +====== + +.. currentmodule:: bootlace.util + +.. autofunction:: render diff --git a/docs/reference.rst b/docs/reference.rst index 139a1b9..72cfc80 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -6,3 +6,9 @@ API Reference reference/breadcrumbs reference/forms reference/icon + reference/image + reference/link + reference/nav + reference/layout + reference/table + reference/tools diff --git a/docs/reference/image.rst b/docs/reference/image.rst new file mode 100644 index 0000000..4e575e2 --- /dev/null +++ b/docs/reference/image.rst @@ -0,0 +1,4 @@ +Images +====== + +.. automodapi:: bootlace.image diff --git a/docs/reference/layout.rst b/docs/reference/layout.rst new file mode 100644 index 0000000..8e38662 --- /dev/null +++ b/docs/reference/layout.rst @@ -0,0 +1,6 @@ +Layout, sizing and colors +========================= + +.. automodapi:: bootlace.style + +.. automodapi:: bootlace.size diff --git a/docs/reference/link.rst b/docs/reference/link.rst new file mode 100644 index 0000000..5bed212 --- /dev/null +++ b/docs/reference/link.rst @@ -0,0 +1,4 @@ +Links +===== + +.. automodapi:: bootlace.links diff --git a/docs/reference/nav.rst b/docs/reference/nav.rst new file mode 100644 index 0000000..008b693 --- /dev/null +++ b/docs/reference/nav.rst @@ -0,0 +1,7 @@ +Navigation +========== + +.. automodapi:: bootlace.nav + +.. automodapi:: bootlace.nav.elements + :allowed-package-names: bootlace.nav diff --git a/docs/reference/table.rst b/docs/reference/table.rst new file mode 100644 index 0000000..f0df752 --- /dev/null +++ b/docs/reference/table.rst @@ -0,0 +1,5 @@ +Tables +====== + +.. automodapi:: bootlace.table + :allowed-package-names: bootlace.table diff --git a/docs/reference/tools.rst b/docs/reference/tools.rst new file mode 100644 index 0000000..bca2b71 --- /dev/null +++ b/docs/reference/tools.rst @@ -0,0 +1,5 @@ +Tools and Utilities +=================== + +.. automodapi:: bootlace.util + :include-all-objects: diff --git a/src/bootlace/image.py b/src/bootlace/image.py index 8b87e7f..751ea21 100644 --- a/src/bootlace/image.py +++ b/src/bootlace/image.py @@ -1,12 +1,23 @@ import attrs from dominate import tags +__all__ = ["Image"] + @attrs.define(kw_only=True, frozen=True) class Image: + """An image tag""" + + #: Alt text for the image alt: str + + #: The URL for the image src: str + + #: The width of the image, in px width: int + + #: The height of the image, in px height: int def __tag__(self) -> tags.html_tag: diff --git a/src/bootlace/links.py b/src/bootlace/links.py index 9929fde..a37b036 100644 --- a/src/bootlace/links.py +++ b/src/bootlace/links.py @@ -9,6 +9,8 @@ from .util import is_active_endpoint from .util import MaybeTaggable +__all__ = ["Link", "View"] + @attrs.define(kw_only=True, frozen=True) class LinkBase(abc.ABC): @@ -33,22 +35,40 @@ def __tag__(self) -> tags.html_tag: @attrs.define(kw_only=True, frozen=True) class Link(LinkBase): + """A raw link to a URL.""" + + #: The URL to link to url: str + + #: Whether the link is active active: bool = False + + #: Whether the link is enabled enabled: bool = True @attrs.define(kw_only=True, frozen=True) class View(LinkBase): + """Link to a Flask view.""" + + #: The endpoint to link to, for use with Flask's :func:`~flask.url_for` endpoint: str + + #: The keyword arguments to pass to :func:`~flask.url_for` url_kwargs: dict[str, Any] = attrs.field(factory=dict) + + #: Whether to ignore the query string when checking if the link is active ignore_query: bool = True + + #: Whether the link is enabled. enabled: bool = True @property def url(self) -> str: + """The URL to link to, constructed using :func:`~flask.url_for`.""" return url_for(self.endpoint, **self.url_kwargs) @property def active(self) -> bool: + """Whether the link is active, based on the current request endpoint.""" return is_active_endpoint(self.endpoint, self.url_kwargs, self.ignore_query) diff --git a/src/bootlace/nav/bar.py b/src/bootlace/nav/bar.py index d96b7de..f545b49 100644 --- a/src/bootlace/nav/bar.py +++ b/src/bootlace/nav/bar.py @@ -14,10 +14,25 @@ @attrs.define class NavBar(NavElement): + """A navigation bar, typically at the top of the page + + This is usually the primary navigation for a site. + """ + + #: The ID of the navbar id: str = attrs.field(factory=element_id.factory("navbar")) + + #: The elements in the navbar items: list[NavElement] = attrs.field(factory=list) + + #: The size of the navbar, if any, used to select when it + #: should expand or collapse expand: SizeClass | None = SizeClass.LARGE + + #: The color of the navbar, if using a bootstrap color class color: ColorClass | None = ColorClass.TERTIARY + + #: Whether the navbar should be fluid (e.g. full width) fluid: bool = True def __tag__(self) -> tags.html_tag: @@ -43,6 +58,13 @@ def __tag__(self) -> tags.html_tag: @attrs.define class Brand(Link): + """The brand for the navbar, typically the site's logo or name + + You can pass :class:`~bootlace.links.Link` or :class:`~bootlace.links.View` + as the source link, and + """ + + #: The ID of the brand id: str = attrs.field(factory=element_id.factory("navbar-brand")) def __tag__(self) -> tags.html_tag: diff --git a/src/bootlace/nav/core.py b/src/bootlace/nav/core.py index 15aef86..01e5dbd 100644 --- a/src/bootlace/nav/core.py +++ b/src/bootlace/nav/core.py @@ -34,10 +34,12 @@ class NavElement: @property def active(self) -> bool: + """Whether the element is active""" return False @property def enabled(self) -> bool: + """Whether the element is enabled""" return True def __tag__(self) -> tags.html_tag: @@ -45,6 +47,7 @@ def __tag__(self) -> tags.html_tag: return tags.comment(f"unhandled element {self.__class__.__name__}") def element_state(self, tag: tags.html_tag) -> tags.html_tag: + """Apply :attr:`active` and :attr:`enabled` states to the tag.""" if self.active: tag.classes.add("active") tag.attributes["aria-current"] = "page" @@ -57,28 +60,37 @@ def element_state(self, tag: tags.html_tag) -> tags.html_tag: @attrs.define class Link(NavElement): + """A link in the nav bar, either for a view or a literal URL""" + #: The link to display, either a URL or a view link: links.LinkBase + + #: The ID of the element id: str = attrs.field(factory=element_id.factory("nav-link")) @classmethod def with_url(cls, url: str, text: str | Image, **kwargs: Any) -> "Link": + """Create a link with a URL.""" return cls(link=links.Link(url=url, text=text, **kwargs)) @classmethod def with_view(cls, endpoint: str, text: str | Image, **kwargs: Any) -> "Link": + """Create a link with a view.""" return cls(link=links.View(endpoint=endpoint, text=text, **kwargs)) @property def active(self) -> bool: + """Whether the link is active.""" return self.link.active @property def enabled(self) -> bool: + """Whether the link is enabled.""" return self.link.enabled @property def url(self) -> str: + """The URL for the link.""" return self.link.url def __tag__(self) -> tags.html_tag: @@ -91,6 +103,7 @@ def __tag__(self) -> tags.html_tag: @attrs.define class Separator(NavElement): + """A separator in dropdown menus""" def __tag__(self) -> tags.html_tag: return tags.hr(cls="dropdown-divider") @@ -98,6 +111,7 @@ def __tag__(self) -> tags.html_tag: @attrs.define class Text(NavElement): + """A text element in the nav bar""" text: str @@ -112,6 +126,8 @@ def __tag__(self) -> tags.html_tag: @attrs.define class SubGroup(NavElement): + """Any grouping of items in the nav bar""" + items: list[NavElement] = attrs.field(factory=list) @property diff --git a/src/bootlace/nav/nav.py b/src/bootlace/nav/nav.py index c22fa3f..3f30a0f 100644 --- a/src/bootlace/nav/nav.py +++ b/src/bootlace/nav/nav.py @@ -10,8 +10,15 @@ @attrs.define class Nav(SubGroup): + """A navigation bar""" + + #: The ID of the nav id: str = attrs.field(factory=element_id.factory("nav")) + + #: The style of the nav style: NavStyle = NavStyle.PLAIN + + #: The alignment of the elments in the nav alignment: NavAlignment = NavAlignment.DEFAULT def __tag__(self) -> tags.html_tag: @@ -36,7 +43,12 @@ def __tag__(self) -> tags.html_tag: @attrs.define class Dropdown(SubGroup): + """A dropdown menu in the nav bar""" + + #: The title of the dropdown title: str = attrs.field(kw_only=True) + + #: The ID of the dropdown id: str = attrs.field(factory=element_id.factory("bs-dropdown")) def __tag__(self) -> tags.html_tag: diff --git a/src/bootlace/size.py b/src/bootlace/size.py index f47ed37..53add65 100644 --- a/src/bootlace/size.py +++ b/src/bootlace/size.py @@ -2,14 +2,28 @@ class SizeClass(enum.Enum): + """Bootstrap size classes""" + + #: Extra-small is the default size class used when none is specified. < 576px EXTRA_SMALL = None + + #: Small size class <768px SMALL = "sm" + + #: Medium size class <992px MEDIUM = "md" + + #: Large size class <1200px LARGE = "lg" + + #: Extra-large size class <1400px EXTRA_LARGE = "xl" + + #: Extra-extra-large size class >=1400px EXTRA_EXTRA_LARGE = "xxl" def add_to_class(self, cls: str) -> str: + """Add the size class to the given class.""" if self.value: return f"{cls}-{self.value}" else: diff --git a/src/bootlace/style.py b/src/bootlace/style.py index 1932ee5..376cef3 100644 --- a/src/bootlace/style.py +++ b/src/bootlace/style.py @@ -2,17 +2,40 @@ class ColorClass(enum.Enum): + """Bootstrap color classes""" + + #: Default foreground (color) and background, including components. + BODY = None + + #: Main theme color, used for hyperlinks, focus styles, and component and form active states. PRIMARY = "primary" + + #: Secondary theme color, used for secondary buttons and form elements. SECONDARY = "secondary" + + #: Tertiary theme color, used for tertiary buttons and form elements. TERTIARY = "tertiary" + + #: Success state color, used for success messages and indicators. SUCCESS = "success" + + #: Danger state color, used for error messages and indicators. DANGER = "danger" + + #: Warning state color, used for warning messages and indicators. WARNING = "warning" + + #: Info state color, used for informational messages and indicators. INFO = "info" + + #: Additional theme option for less contrasting colors. LIGHT = "light" + + #: Additional theme option for higher contrasting colors. DARK = "dark" - WHITE = "white" - TRANSPARENT = "transparent" def add_to_class(self, cls: str) -> str: - return f"{cls}-{self.value}" + """Add the color class name to the given class.""" + if self.value: + return f"{cls}-{self.value}" + return cls diff --git a/src/bootlace/table/base.py b/src/bootlace/table/base.py index 097affd..bf1028e 100644 --- a/src/bootlace/table/base.py +++ b/src/bootlace/table/base.py @@ -16,7 +16,12 @@ @attrs.define class Heading: + """A heading for a table column.""" + + #: The text of the heading text: str + + #: The icon for the heading, in place of the text icon: Icon | None = attrs.field(default=None, converter=maybe(Icon)) # type: ignore def __tag__(self) -> tags.html_tag: @@ -29,7 +34,13 @@ def __tag__(self) -> tags.html_tag: @attrs.define class ColumnBase(ABC): + """Base class for table columns. + + Subclasses must implement the :meth:`cell` method.""" + + #: The heading for the column heading: Heading = attrs.field(converter=maybe(Heading)) # type: ignore + _attribute: str | None = None def __set_name__(self, owner: type, name: str) -> None: @@ -37,12 +48,14 @@ def __set_name__(self, owner: type, name: str) -> None: @property def attribute(self) -> str: + """The attribute name for the column.""" if self._attribute is None: raise ValueError("column must be named in Table or attribute= parameter must be provided") return self._attribute @abstractmethod def cell(self, value: Any) -> tags.html_tag: + """Return the cell for the column as an HTML tag.""" raise NotImplementedError("Subclasses must implement this method") diff --git a/src/bootlace/table/columns.py b/src/bootlace/table/columns.py index 0d883ce..da3a10c 100644 --- a/src/bootlace/table/columns.py +++ b/src/bootlace/table/columns.py @@ -15,27 +15,42 @@ @attrs.define class Column(ColumnBase): + """A column in a table, which shows the value of an attribute. + + No special formatting is applied to the attribute, it is rendered as text.""" def cell(self, value: Any) -> tags.html_tag: + """Return the cell for the column as an HTML tag.""" return text(str(getattr(value, self.attribute))) @attrs.define class EditColumn(ColumnBase): + """A column which links to an edit view for the value. + + This is commonly shown as e.g. the name of the item, which links to the edit view.""" + + #: The endpoint for the edit view endpoint: str = attrs.field(default=".edit") def cell(self, value: Any) -> tags.html_tag: + """Return the cell for the column as an HTML tag.""" id = getattr(value, "id", None) return tags.a(getattr(value, self.attribute), href=url_for(self.endpoint, id=id)) @attrs.define class CheckColumn(ColumnBase): + """A column which shows a checkmark or X based on the value of the attribute.""" + #: The icon for a true value yes: Icon = attrs.field(default=Icon("check", width=16, height=16)) + + #: The icon for a false value no: Icon = attrs.field(default=Icon("x", width=16, height=16)) def cell(self, value: Any) -> tags.html_tag: + """Return the cell for the column as an HTML tag.""" if getattr(value, self.attribute): return as_tag(self.yes) return as_tag(self.no) @@ -43,6 +58,8 @@ def cell(self, value: Any) -> tags.html_tag: @attrs.define class Datetime(ColumnBase): + """A column which shows a datetime attribute as an ISO formatted string.""" def cell(self, value: Any) -> tags.html_tag: + """Return the cell for the column as an HTML tag.""" return text(getattr(value, self.attribute).isoformat()) diff --git a/src/bootlace/util.py b/src/bootlace/util.py index 4e28639..c67164e 100644 --- a/src/bootlace/util.py +++ b/src/bootlace/util.py @@ -19,6 +19,20 @@ T = TypeVar("T") +__all__ = [ + "BootlaceWarning", + "Classes", + "HtmlIDScope", + "IntoTag", + "MaybeTaggable", + "Taggable", + "as_tag", + "ids", + "is_active_endpoint", + "maybe", + "render", +] + class BootlaceWarning(UserWarning): """A warning specific to Bootlace""" @@ -30,15 +44,21 @@ def _monkey_patch_dominate() -> None: class Taggable(Protocol): + """Protocol for objects that can be converted to a tag.""" + def __tag__(self) -> tags.html_tag: ... +#: A type that can be converted to a tag IntoTag = Taggable | tags.html_tag +#: A type that can be converted to a tag via :func:`as_tag` MaybeTaggable = IntoTag | str | Iterable[Taggable | tags.html_tag] def as_tag(item: Taggable) -> tags.html_tag: + """Convert an item to a dominate tag.""" + if isinstance(item, tags.html_tag): return item if hasattr(item, "__tag__"): @@ -53,10 +73,13 @@ def as_tag(item: Taggable) -> tags.html_tag: def render(item: Taggable) -> Markup: + """Render an item to a Markup object.""" return Markup(as_tag(item).render()) class Classes: + """A helper for manipulating the class attribute on a tag.""" + def __init__(self, tag: tags.html_tag) -> None: self.tag = tag @@ -94,6 +117,8 @@ def swap(self, old: str, new: str) -> tags.html_tag: @attrs.define class HtmlIDScope: + """A helper for generating unique HTML IDs.""" + scopes: collections.defaultdict[str, itertools.count] = attrs.field( factory=lambda: collections.defaultdict(itertools.count) ) @@ -112,6 +137,8 @@ def factory(self, scope: str) -> functools.partial: def maybe(cls: type[T]) -> Callable[[str | T], T]: + """Convert a string to a class instance if necessary.""" + def converter(value: str | T) -> T: if isinstance(value, str): return cls(value) # type: ignore