Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework the parameter table style #872

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Rework the parameter table style #872

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
28014e3
Rework the parameter table style, fixes #868
tristanlatr Jan 24, 2025
dc9aabe
Instead of adding hait lines, use the backup ground color to differen…
tristanlatr Jan 30, 2025
bc4aeb7
Refactor and add type annotations
tristanlatr Jan 30, 2025
0607378
15% of oppacity is enough to clearly see a difference
tristanlatr Jan 30, 2025
2c53546
Make the hightlight color 10% less yellow
tristanlatr Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 36 additions & 32 deletions pydoctor/epydoc2stan.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ def format(self) -> Generator[Tag, None, None]:
yield tags.td(tags.code(self.type), class_="fieldArgContainer")
yield tags.td(self.body or self._UNDOCUMENTED)

def format_desc_list(label: str, descs: Sequence[FieldDesc]) -> Iterator[Tag]:
def format_desc_list(label: str, descs: Sequence[FieldDesc]) -> list[Tag]:
"""
Format list of L{FieldDesc}. Used for param, returns, raises, etc.

Expand All @@ -148,23 +148,27 @@ def format_desc_list(label: str, descs: Sequence[FieldDesc]) -> Iterator[Tag]:

@arg label: Section "mini heading"
@arg descs: L{FieldDesc}s
@returns: Each row as iterator or None if no C{descs} id provided.
@returns: A list containing a single table tag or an empty list if no C{descs} are provided.
"""
if not descs:
return
# <label>
row = tags.tr(class_="fieldStart")
row(tags.td(class_="fieldName", colspan="2")(label))
# yield the first row.
yield row
# yield descriptions.
for d in descs:
row = tags.tr()
# <name>: <type> | <desc>
# or
# <desc ... >
row(d.format())
if not descs:
return []

def rows() -> Iterator[Tag]:
# <label>
row = tags.tr(class_="fieldStart")
row(tags.td(class_="fieldName", colspan="2")(label))
# yield the first row.
yield row
# yield descriptions.
for d in descs:
row = tags.tr()
# <name>: <type> | <desc>
# or
# <desc ... >
row(d.format())
yield row

return [tags.table(class_='fieldTable')(*rows())]

@attr.s(auto_attribs=True)
class Field:
Expand Down Expand Up @@ -205,7 +209,7 @@ def report(self, message: str) -> None:
self.source.report(message, lineno_offset=self.lineno, section='docstring')


def format_field_list(singular: str, plural: str, fields: Sequence[Field]) -> Iterator[Tag]:
def format_field_list(singular: str, plural: str, fields: Sequence[Field]) -> list[Tag]:
"""
Format list of L{Field} object. Used for notes, see also, authors, etc.

Expand All @@ -216,20 +220,23 @@ def format_field_list(singular: str, plural: str, fields: Sequence[Field]) -> It
| <desc ... > |
+------------------------------------+

@returns: Each row as iterator
@returns: A list containing a single table tag or an empty list if no C{fields} are provided.
"""
if not fields:
return
if not fields:
return []

def rows() -> Iterator[Tag]:
label = singular if len(fields) == 1 else plural
row = tags.tr(class_="fieldStart")
row(tags.td(class_="fieldName", colspan="2")(label))
yield row

label = singular if len(fields) == 1 else plural
row = tags.tr(class_="fieldStart")
row(tags.td(class_="fieldName", colspan="2")(label))
yield row
for field in fields:
row = tags.tr()
row(tags.td(colspan="2")(field.format()))
yield row

for field in fields:
row = tags.tr()
row(tags.td(colspan="2")(field.format()))
yield row
return [tags.table(class_='fieldTable')(*rows())]

class VariableArgument(str):
"""
Expand Down Expand Up @@ -558,10 +565,7 @@ def format(self) -> Tag:
for kind, fieldlist in self.unknowns.items():
r += format_desc_list(f"Unknown Field: {kind}", fieldlist)

if any(r):
return tags.table(class_='fieldTable')(r)
else:
return tags.transparent
return tags.transparent(*r)

def reportWarnings(obj: model.Documentable, warns: Sequence[str], **kwargs:Any) -> None:
for message in warns:
Expand Down
52 changes: 35 additions & 17 deletions pydoctor/themes/base/apidocs.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,7 @@ ul ul ul ul ul ul ul {
.fieldTable {
width: 100%;
border: 0;
overflow: hidden;
}

/* Arg name */
Expand All @@ -243,20 +244,43 @@ ul ul ul ul ul ul ul {

.fieldTable tr:not(.fieldStart) td:first-child,
.valueTable tr:not(.fieldStart) td:first-child{
padding: 3px 4px 3px 15px;
padding: 2px 4px 2px 15px;
}

tr.fieldStart{
padding-bottom: 2px;
}

.fieldTable tr td.fieldArgDesc > *:nth-child(1){
padding-top: 0; /* So it's actually aligned vertically */
}

.fieldTable tr td {
padding: 2px;
vertical-align: top;
}

/* Add border to separate parameter rows */
.fieldTable tr:not(:last-of-type):has(.fieldArgContainer):has(+ tr:not(.fieldStart)) {
/* This is a way to add a margin in between table rows */
border-bottom: 5px solid;
border-color: transparent;
}

.fieldTable tr:has(.fieldArgContainer):nth-child(odd) {
background-color: rgba(215, 215, 215, 0.15);
}

/* Argument name + type column table */
.fieldTable tr td.fieldArgContainer {
width: 325px;
max-width: 400px;
word-break: break-word;
}

.fieldTable tr td.fieldArgDesc {
max-width: 600px;
}

/* parameters names in parameters table */
.fieldTable tr td.fieldArgContainer > .fieldArg {
float: left;
Expand Down Expand Up @@ -306,6 +330,11 @@ ul ul ul ul ul ul ul {
width: auto;
}

/* Argument name + type column table */
.fieldTable tr td.fieldArgContainer {
width: 33%;
}

}

@media only screen and (max-width: 820px) {
Expand All @@ -320,24 +349,13 @@ ul ul ul ul ul ul ul {
#splitTables > table tr td:nth-child(2) {
width: 160px;
}
/* Argument name + type column table */
.fieldTable tr td.fieldArgContainer {
width: 170px;
}
.fieldTable {
table-layout: fixed;
}
}

@media only screen and (max-width: 450px) {
/* Attr name column table */
#splitTables > table tr td:nth-child(2) {
width: 100px;
}
/* Argument name + type column table */
.fieldTable tr td.fieldArgContainer {
width: 125px;
}
}

table .package {
Expand Down Expand Up @@ -1129,18 +1147,18 @@ pre.constant-value { padding: .5em; }

/* highlight the targeted item with "#" */
#childList a:target ~ .functionHeader, #childList a:target ~ .functionBody{
background-color: rgb(253, 255, 223);
background-color: rgba(253, 255, 223, 0.9);
}
#childList a:target ~ .functionHeader{
box-shadow: 0px 0px 0px 10px rgb(253, 255, 223);
box-shadow: 0px 0px 0px 10px rgba(253, 255, 223, 0.9);
}
#childList a:target ~ .functionBody{
box-shadow: -2px -8px 0px 13px rgb(253 255 223);
}
/* in class hierarchy */
#summaryTree a:target ~ div {
background-color: rgb(253, 255, 223);
box-shadow: 0px 0px 0px 7px rgb(253, 255, 223);
background-color: rgba(253, 255, 223, 0.9);
box-shadow: 0px 0px 0px 7px rgba(253, 255, 223, 0.9);
}
#summaryTree div {
display: inline-table;
Expand Down
3 changes: 1 addition & 2 deletions pydoctor/themes/readthedocs/readthedocstheme.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -747,8 +747,7 @@ input[type="search"] {
border-left: 3px solid rgb(80, 80, 90);
}
#childList a:target ~ .functionBody{
background-color: transparent;
box-shadow: none;
box-shadow: 7px 1px 0px 3px rgba(253, 255, 223, 0.9), -36px 1px 0px 3px rgba(253, 255, 223, 0.9);
}

@font-face {
Expand Down
Loading