Skip to content

Commit

Permalink
fix lint
Browse files Browse the repository at this point in the history
  • Loading branch information
@epinzur
epinzur committed Oct 9, 2023
1 parent 9012521 commit 1833920
Show file tree
Hide file tree
Showing 6 changed files with 105 additions and 66 deletions.
3 changes: 2 additions & 1 deletion .github/workflows/ci_python.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ jobs:
poetry run black --diff pysrc pytests docs
- name: flake8
run: |
poetry run flake8 pysrc pytests docs
poetry run flake8 pysrc pytests
- name: isort
run: |
poetry run isort --filter-files --diff pysrc pytests docs
Expand Down Expand Up @@ -137,6 +137,7 @@ jobs:
- name: Build docs
run: |
poetry env use 3.11
source $(poetry env info --path)/bin/activate
poetry install --only=dev
nox -s docs-gen
nox -s docs-build
Expand Down
46 changes: 28 additions & 18 deletions python/docs/_scripts/builder.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,13 @@

import logging
import sys

from pathlib import Path
from pydantic import ValidationError

from quartodoc.inventory import create_inventory, convert_inventory
from quartodoc import layout, preview, blueprint, collect
from quartodoc.validation import fmt

from typing import Any, Union

from pydantic import ValidationError
from quartodoc import blueprint, collect, layout, preview
from quartodoc.inventory import convert_inventory, create_inventory
from quartodoc.validation import fmt
from renderer import Renderer
from summarizer import Summarizer

Expand Down Expand Up @@ -136,7 +133,7 @@ def build(self):
convert_inventory(inv, self.out_inventory)

def get_package(self, item: Union[layout.Section, layout.Page]) -> str:
if item.package and f'{item.package}' != "":
if item.package and f"{item.package}" != "":
return item.package
else:
return self.package
Expand Down Expand Up @@ -167,7 +164,10 @@ def write_pages(self):
section_path = location / self.out_index
self.write_page_if_not_exists(section_path, section_text)

is_flat = section.options and section.options.children == layout.ChoicesChildren.flat
is_flat = (
section.options
and section.options.children == layout.ChoicesChildren.flat
)

for page in section.contents:
if isinstance(page, layout.Page):
Expand All @@ -186,24 +186,32 @@ def write_pages(self):
raise NotImplementedError(f"Unsupported section item: {type(page)}")

if len(self.page_map.keys()) > 0:
_log.warning(f'Extra pages: {self.page_map.keys()}')
_log.error(f'Linking between pages may not work properly. Fix the issue and try again')
_log.warning(f"Extra pages: {self.page_map.keys()}")
_log.error(
f"Linking between pages may not work properly. Fix the issue and try again"
)

if len(self.item_map.keys()) > 0:
_log.warning(f'Extra items: {self.item_map.keys()}')
_log.error(f'Linking between pages may not work properly. Fix the issue and try again')
_log.warning(f"Extra items: {self.item_map.keys()}")
_log.error(
f"Linking between pages may not work properly. Fix the issue and try again"
)

def update_page_items(self, page: layout.Page, location: Path, is_flat: bool):
for doc in page.contents:
if isinstance(doc, layout.Doc):
page_path = f'{location}/index.html' if is_flat else f'{location}/{page.path}.html'
page_path = (
f"{location}/index.html"
if is_flat
else f"{location}/{page.path}.html"
)
self.update_items(doc, page_path)
else:
raise NotImplementedError(f"Unsupported page item: {type(doc)}")

def update_items(self, doc: layout.Doc, page_path: str):
name = doc.obj.path
uri = f'{page_path}#{doc.anchor}'
uri = f"{page_path}#{doc.anchor}"

# item corresponding to the specified path ----
# e.g. this might be a top-level import
Expand All @@ -213,7 +221,7 @@ def update_items(self, doc: layout.Doc, page_path: str):
del self.item_map[name]
else:
item = layout.Item(uri=uri, name=name, obj=doc.obj, dispname=None)
_log.warning(f'Missing item, adding it: {item}')
_log.warning(f"Missing item, adding it: {item}")
self.items.append(item)

canonical_path = doc.obj.canonical_path
Expand All @@ -225,8 +233,10 @@ def update_items(self, doc: layout.Doc, page_path: str):
item.uri = uri
del self.item_map[canonical_path]
else:
item = layout.Item(uri=uri, name=canonical_path, obj=doc.obj, dispname=name)
_log.warning(f'Missing item, adding it: {item}')
item = layout.Item(
uri=uri, name=canonical_path, obj=doc.obj, dispname=name
)
_log.warning(f"Missing item, adding it: {item}")
self.items.append(item)

# recurse in 😊
Expand Down
67 changes: 38 additions & 29 deletions python/docs/_scripts/renderer.py
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
from __future__ import annotations

import quartodoc.ast as qast
from typing import Optional, Union

from griffe.docstrings import dataclasses as ds
import quartodoc.ast as qast
from griffe import dataclasses as dc
from tabulate import tabulate
from griffe.docstrings import dataclasses as ds
from plum import dispatch
from typing import Union, Optional
from quartodoc import layout

from summarizer import Summarizer
from tabulate import tabulate


try:
# Name and Expression were moved to expressions in v0.28
Expand Down Expand Up @@ -49,7 +49,7 @@ def sanitize(val: str, allow_markdown=False):
return res


class Renderer():
class Renderer:
"""Render docstrings to markdown."""

summarizer = Summarizer()
Expand All @@ -61,7 +61,7 @@ def _get_display_name(self, el: "dc.Alias | dc.Object"):
display_name = f"**{prefix}.**[**{name}**]{{.red}}"

if isinstance(el, dc.Object):
if 'staticmethod' in el.labels:
if "staticmethod" in el.labels:
display_name = "***static*** " + display_name

text = [display_name]
Expand All @@ -78,23 +78,25 @@ def _fetch_method_parameters(self, el: dc.Function):

return el.parameters

def _render_definition_list(self, title: str, items: [str], title_class: Optional[str] = None) -> str:
def _render_definition_list(
self, title: str, items: [str], title_class: Optional[str] = None
) -> str:
rows = [title]
for item in items:
if len(rows) == 1:
rows.append(f'~ {item}')
rows.append(f"~ {item}")
else:
rows.append(f' {item}')
rows.append(f" {item}")
if title_class:
rows.insert(0, f':::{{.{title_class}}}')
rows.append(':::')
rows.insert(0, f":::{{.{title_class}}}")
rows.append(":::")
return "\n" + "\n".join(rows)

def _render_header(self, title: str, order: Optional[int] = None) -> str:
text = ["---"]
text.append(f'title: {title}')
text.append(f"title: {title}")
if order:
text.append(f'order: {order}')
text.append(f"order: {order}")
text.append("---")
return "\n".join(text)

Expand Down Expand Up @@ -190,7 +192,7 @@ def render(self, el: layout.Page, is_flat: bool = False):
if el.summary:
if el.summary.name:
if is_flat:
rows.append(f'## {el.summary.name}')
rows.append(f"## {el.summary.name}")
else:
rows.append(self._render_header(el.summary.name))
if el.summary.desc:
Expand All @@ -206,7 +208,9 @@ def render(self, el: layout.Doc):
raise NotImplementedError(f"Unsupported Doc type: {type(el)}")

@dispatch
def render(self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = False) -> str:
def render(
self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = False
) -> str:
title = "" if is_flat else self._render_header(el.name)

sig = self.signature(el)
Expand All @@ -219,7 +223,8 @@ def render(self, el: Union[layout.DocClass, layout.DocModule], is_flat: bool = F
if raw_attrs and not _has_attr_section(el.obj.docstring):
attr_rows = map(self.render, raw_attrs)
attr_text = self._render_definition_list(
"Attributes:", attr_rows, title_class="highlight")
"Attributes:", attr_rows, title_class="highlight"
)
body_rows.extend(attr_text.split("\n"))

# add classes
Expand Down Expand Up @@ -358,15 +363,17 @@ def render(self, el: ds.DocstringSectionParameters):
for param in el.value:
name = sanitize(param.name)
anno = self.render_annotation(param.annotation)
default = f', default: {escape(param.default)}' if param.default else ""
default = f", default: {escape(param.default)}" if param.default else ""

rows.append(f'{prefix}**{name}** ({anno}{default})')
rows.append(f"{prefix}**{name}** ({anno}{default})")
rows.append("")
for row in param.description.split("\n"):
rows.append(f'{follow}{row}')
rows.append(f"{follow}{row}")
rows.append("")

return self._render_definition_list("Parameters:", rows, title_class="highlight")
return self._render_definition_list(
"Parameters:", rows, title_class="highlight"
)

# attributes ----

Expand All @@ -380,13 +387,15 @@ def render(self, el: ds.DocstringSectionAttributes):
for attr in el.value:
name = sanitize(attr.name)
anno = self.render_annotation(attr.annotation)
rows.append(f'{prefix}**{name}** ({anno})')
rows.append(f"{prefix}**{name}** ({anno})")
rows.append("")
for row in attr.description.split("\n"):
rows.append(f'{follow}{row}')
rows.append(f"{follow}{row}")
rows.append("")

return self._render_definition_list("Attributes:", rows, title_class="highlight")
return self._render_definition_list(
"Attributes:", rows, title_class="highlight"
)

# examples ----

Expand Down Expand Up @@ -419,7 +428,7 @@ def render(self, el: ds.DocstringSectionReturns):
title = prefix
name = sanitize(item.name)
if name:
title += f'**{name}**'
title += f"**{name}**"

return_type = self.render_annotation(item.annotation)
if return_type:
Expand All @@ -431,7 +440,7 @@ def render(self, el: ds.DocstringSectionReturns):
if item.description:
rows.append("")
for row in item.description.split("\n"):
rows.append(f'{follow}{row}')
rows.append(f"{follow}{row}")
rows.append("")

return self._render_definition_list("Returns:", rows, title_class="highlight")
Expand All @@ -446,10 +455,10 @@ def render(self, el: ds.DocstringSectionRaises):
for item in el.value:
# name = sanitize(item.name)
anno = self.render_annotation(item.annotation)
rows.append(f'{prefix}{anno}')
rows.append(f"{prefix}{anno}")
rows.append("")
for row in item.description.split("\n"):
rows.append(f'{follow}{row}')
rows.append(f"{follow}{row}")
rows.append("")

return self._render_definition_list("Raises:", rows, title_class="highlight")
Expand All @@ -465,7 +474,7 @@ def render(self, el: ds.DocstringSectionAdmonition) -> str:
rows.append(f'::: {{.callout-tip title="{el.title}"}}')

rows.append(el.value.description)
rows.append(':::')
rows.append(":::")

return "\n".join(rows)

Expand Down
7 changes: 4 additions & 3 deletions python/docs/_scripts/summarizer.py
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
from __future__ import annotations

from griffe.docstrings import dataclasses as ds
from typing import Optional, Union

from griffe import dataclasses as dc
from griffe.docstrings import dataclasses as ds
from plum import dispatch
from typing import Union, Optional
from quartodoc import layout


class Summarizer():
class Summarizer:
"""Summarize docstrings to markdown."""

@staticmethod
Expand Down
16 changes: 9 additions & 7 deletions python/docs/examples/bluesky.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,13 +79,15 @@ async def receive_at(message) -> None:

# The parsing produces a hot mess of incompatible types, so we build
# a dict from scratch to simplify.
posts.add_rows({
"record": dict(new_post["record"]),
"uri": new_post["uri"],
"cid": new_post["cid"],
"author": new_post["author"],
"ts": time.time(),
})
posts.add_rows(
{
"record": dict(new_post["record"]),
"uri": new_post["uri"],
"cid": new_post["cid"],
"author": new_post["author"],
"ts": time.time(),
}
)

# Handler for values emitted by Kaskada.
async def receive_outputs():
Expand Down
Loading

0 comments on commit 1833920

Please sign in to comment.