writeadoc 0.1.0__tar.gz

writeadoc-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: writeadoc
+Version: 0.1.0
+Summary: Focus on your content and let WriteADoc take care of the rest
+Author-email: Juan Pablo Scaletti <juanpablo@jpscaletti.com>
+Project-URL: Homepage, https://writeadoc.scaletti.dev/
+Project-URL: GitHub, https://github.com/jpsca/writeadoc
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: docstring-parser>=0.17.0
+Requires-Dist: hecto>=2.0.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: jx>=0.2.0
+Requires-Dist: markdown>=3.8.2
+Requires-Dist: pygments>=2.19.2
+Requires-Dist: pymdown-extensions>=10.16
+Requires-Dist: strictyaml>=1.7.3
+Requires-Dist: watchdog>=6.0.0
+
+# <img src="./docs/logo.png" align="middle" />
+
+Focus on your content and let WriteADoc take care of the rest
+
+
+## Main features
+
+* **Simple yet powerful formatting**: Write in Markdown, plus enjoy powerful features like callbacks, flexible code blocks, and _much more_.
+* **Built-in full-text search**: Automatically generates a full-text search index for you. No third-party service required.
+* **Multi-language & multi-version capable**: Easily manage documentation for multiple versions and languages, right out of the box. No plugins or complicated setup needed.
+* **Works on all devices and with light/dark modes**: WriteADoc automatically adapts to perfectly fit the available screen, no matter the type or size of the viewing device and whether you're an early bird or a night owl.
+* **Always yours**: A static site means you can host it anywhere. You own your content and your site. No need to trust your product knowledge to third-party platforms.
+
+
+## Documentation
+
+[Read the WriteADoc docs][docs] (they’re built with WriteADoc!)
+
+
+## License
+
+MIT
+
+Copyright (c) 2025–present Juan-Pablo Scaletti and [contributors][contributors]
+
+[docs]: https://writeadoc.scaletti.dev/
+[contributors]: https://github.com/jpsca/writeadoc/graphs/contributors
+[issues]: https://github.com/jpsca/writeadoc/issues

writeadoc-0.1.0/README.md

@@ -0,0 +1,28 @@
+# <img src="./docs/logo.png" align="middle" />
+
+Focus on your content and let WriteADoc take care of the rest
+
+
+## Main features
+
+* **Simple yet powerful formatting**: Write in Markdown, plus enjoy powerful features like callbacks, flexible code blocks, and _much more_.
+* **Built-in full-text search**: Automatically generates a full-text search index for you. No third-party service required.
+* **Multi-language & multi-version capable**: Easily manage documentation for multiple versions and languages, right out of the box. No plugins or complicated setup needed.
+* **Works on all devices and with light/dark modes**: WriteADoc automatically adapts to perfectly fit the available screen, no matter the type or size of the viewing device and whether you're an early bird or a night owl.
+* **Always yours**: A static site means you can host it anywhere. You own your content and your site. No need to trust your product knowledge to third-party platforms.
+
+
+## Documentation
+
+[Read the WriteADoc docs][docs] (they’re built with WriteADoc!)
+
+
+## License
+
+MIT
+
+Copyright (c) 2025–present Juan-Pablo Scaletti and [contributors][contributors]
+
+[docs]: https://writeadoc.scaletti.dev/
+[contributors]: https://github.com/jpsca/writeadoc/graphs/contributors
+[issues]: https://github.com/jpsca/writeadoc/issues

writeadoc-0.1.0/pyproject.toml

@@ -0,0 +1,179 @@
+[project]
+name = "writeadoc"
+version = "0.1.0"
+description = "Focus on your content and let WriteADoc take care of the rest"
+authors = [
+    {name = "Juan Pablo Scaletti", email = "juanpablo@jpscaletti.com"},
+]
+license = { "file" = "MIT-LICENSE" }
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "docstring-parser>=0.17.0",
+    "hecto>=2.0.1",
+    "jinja2>=3.1.6",
+    "jx>=0.2.0",
+    "markdown>=3.8.2",
+    "pygments>=2.19.2",
+    "pymdown-extensions>=10.16",
+    "strictyaml>=1.7.3",
+    "watchdog>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://writeadoc.scaletti.dev/"
+GitHub = "https://github.com/jpsca/writeadoc"
+
+[dependency-groups]
+dev = [
+    "ipdb>=0.13.13",
+    "ruff>=0.12.4",
+    "tox-uv",
+    "ty>=0.0.1a15",
+]
+test = [
+    "pytest>=8.4.1",
+]
+
+[project.scripts]
+writeadoc = "writeadoc.cli:run"
+
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+writeadoc = [
+    "blueprint/**",
+]
+[tool.setuptools.exclude-package-data]
+"*" = [
+    "**/__pycache__",
+    "*.pyc",
+    "*.pyo",
+]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "TYPE_CHECKING",
+    "def __repr__",
+    "def __str__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:"
+]
+omit = [
+    "src/writeadoc/blueprint/**",
+]
+
+[tool.coverage.html]
+directory = "covreport"
+
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules --ignore=src/writeadoc/blueprint"
+
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+env_list =
+    3.12
+    3.13
+    3.14
+
+[testenv]
+runner = uv-venv-lock-runner
+dependency_groups =
+    dev
+    test
+commands =
+    pytest -x src/writeadoc tests
+"""
+
+[tool.ruff]
+line-length = 90
+indent-width = 4
+target-version = "py312"
+exclude = [
+  ".*",
+  "_build",
+  "build",
+  "covreport",
+  "dist",
+  "src/writeadoc/blueprint/*",
+]
+include = ["*.py"]
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+#
+# This is currently disabled by default, but it is planned for this
+# to be opt-out in the future.
+docstring-code-format = false
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+#
+# This only has an effect when the `docstring-code-format` setting is
+# enabled.
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+
+ignore = [
+	# x is too complex
+	"C901",
+	# whitespace before ':'
+	"E203",
+	"E501",
+	# x defined from star imports
+	"F405",
+	# line break before binary operator
+	"W505",
+	"W605",
+]
+select = [
+	# bugbear
+	"B",
+	# mccabe"", comprehensions, commas
+	"C",
+	# pycodestyle errors
+	"E",
+	# pyflakes
+	"F",
+	# logging format
+	"G",
+	# imports
+	"I",
+	# quotes
+	"Q",
+	# pycodestyle warnings
+	"W",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["writeadoc"]
+known-local-folder = ["src/writeadoc"]
+
+# Use two line after imports.
+lines-after-imports = 2

writeadoc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

writeadoc-0.1.0/src/writeadoc/__init__.py

@@ -0,0 +1,7 @@
+from .exceptions import *  # noqa
+from .main import Docs  # noqa
+from .types import *  # noqa
+from .utils import (
+    DEFAULT_MD_EXTENSIONS,  # noqa
+    DEFAULT_MD_CONFIG,  # noqa
+)

writeadoc-0.1.0/src/writeadoc/autodoc.py

@@ -0,0 +1,303 @@
+import inspect
+import typing as t
+from dataclasses import dataclass, field
+from importlib import import_module
+
+from docstring_parser import parse
+from docstring_parser.common import (
+    DocstringDeprecated,
+    DocstringExample,
+    DocstringParam,
+    DocstringRaises,
+    DocstringReturns,
+)
+
+
+@dataclass(slots=True)
+class AttrDocstring:
+    symbol: str = ""
+    name: str = ""
+    label: str = "attribute"
+    short_description: str = ""
+    long_description: str = ""
+    description: str = ""
+
+
+@dataclass(slots=True)
+class Docstring:
+    name: str = ""
+    symbol: str = ""
+    label: str = ""
+    signature: str = ""
+    params: list[AttrDocstring] = field(default_factory=list)
+
+    # First paragraph of the description
+    short_description: str = ""
+    # Rest of the description
+    long_description: str = ""
+    # The full description
+    description: str = ""
+
+    # Deprecation notes
+    deprecation: DocstringDeprecated | None = None
+    # A list of examples.
+    examples: list[DocstringExample] = field(default_factory=list)
+    # Return information.
+    returns: DocstringReturns | None = None
+    # A list of multiple return values.
+    many_returns: list[DocstringReturns] = field(default_factory=list)
+    # A list of exceptions that the function may raise.
+    raises: list[DocstringRaises] = field(default_factory=list)
+
+    # Inheritance information
+    bases: list[str] = field(default_factory=list)
+    # Attributes
+    attrs: list[AttrDocstring] = field(default_factory=list)
+    # Properties
+    properties: list[AttrDocstring] = field(default_factory=list)
+    # Methods
+    methods: list["Docstring"] = field(default_factory=list)
+
+
+class Autodoc:
+    def __call__(
+        self,
+        name: str,
+        *,
+        include: tuple[str, ...] = (),
+        exclude: tuple[str, ...] = (),
+    ) -> Docstring:
+        module_name, obj_name = name.rsplit(".", 1)
+        module = import_module(module_name)
+        assert module
+        obj = getattr(module, obj_name, None)
+        if not obj:
+            raise ValueError(f"Object {obj_name} not found in module {module_name}")
+
+        return self.autodoc_obj(obj, include=include, exclude=exclude)
+
+    def autodoc_obj(
+        self,
+        obj: t.Any,
+        *,
+        include: tuple[str, ...] = (),
+        exclude: tuple[str, ...] = (),
+    ) -> Docstring:
+        if inspect.isclass(obj):
+            ds = self.autodoc_class(obj, include=include, exclude=exclude)
+        elif inspect.isfunction(obj) or inspect.ismethod(obj):
+            ds = self.autodoc_function(obj)
+        else:
+            ds = Docstring()
+        return ds
+
+    def autodoc_class(
+        self,
+        obj: t.Any,
+        *,
+        symbol: str = "class",
+        include: tuple[str, ...] = (),
+        exclude: tuple[str, ...] = (),
+    ) -> Docstring:
+        init = getattr(obj, "__init__", None)
+        obj_name = obj.__name__
+        ds = parse(obj.__doc__ or init.__doc__ or "")
+
+        description = (ds.description or "").strip()
+        short_description, long_description = self.split_description(description)
+
+        params = []
+        attrs = []
+        properties = []
+        methods = []
+
+        for param in ds.params:
+            doc = self.autodoc_attr(param)
+            if param.args[0] == "param":
+                params.append(doc)
+            elif param.args[0] == "attribute":
+                attrs.append(doc)
+
+        for name, value in inspect.getmembers(obj):
+            if name.startswith("_") and name not in include:
+                continue
+            if name in exclude:
+                continue
+            if inspect.isfunction(value):
+                methods.append(self.autodoc_function(value, symbol="method"))
+                continue
+            if isinstance(value, property):
+                properties.append(self.autodoc_property(name, value))
+                continue
+
+        if ds.deprecation:
+            ds.deprecation.description = (ds.deprecation.description or "").strip()
+        if ds.returns:
+            ds.returns.description = (ds.returns.description or "").strip()
+        for meta in ds.raises:
+            meta.description = (meta.description or "").strip()
+        for meta in ds.many_returns:
+            meta.description = (meta.description or "").strip()
+        for meta in ds.examples:
+            meta.snippet = (meta.snippet or "").strip()
+            meta.description = (meta.description or "").strip()
+
+        return Docstring(
+            symbol=symbol,
+            name=obj_name,
+            signature=self.get_signature(obj_name, init),
+            params=params,
+            short_description=short_description,
+            long_description=long_description,
+            description=description,
+            deprecation=ds.deprecation,
+            returns=ds.returns,
+            raises=ds.raises,
+            examples=ds.examples,
+            many_returns=ds.many_returns,
+            bases=[base.__name__ for base in obj.__bases__ if base.__name__ != "object"],
+            attrs=attrs,
+            properties=properties,
+            methods=methods,
+        )
+
+    def autodoc_function(self, obj: t.Any, *, symbol: str = "function") -> Docstring:
+        obj_name = obj.__name__
+        ds = parse(obj.__doc__ or "")
+
+        description = (ds.description or "").strip()
+        short_description, long_description = self.split_description(description)
+        params = [self.autodoc_attr(param) for param in ds.params]
+
+        if ds.deprecation:
+            ds.deprecation.description = (ds.deprecation.description or "").strip()
+        if ds.returns:
+            ds.returns.description = (ds.returns.description or "").strip()
+        for meta in ds.raises:
+            meta.description = (meta.description or "").strip()
+        for meta in ds.many_returns:
+            meta.description = (meta.description or "").strip()
+        for meta in ds.examples:
+            meta.snippet = (meta.snippet or "").strip()
+            meta.description = (meta.description or "").strip()
+
+        return Docstring(
+            name=obj_name,
+            symbol=symbol,
+            signature=self.get_signature(obj_name, obj),
+            params=params,
+            short_description=short_description,
+            long_description=long_description,
+            description=description,
+            deprecation=ds.deprecation,
+            returns=ds.returns,
+            raises=ds.raises,
+            examples=ds.examples,
+            many_returns=ds.many_returns,
+        )
+
+    def autodoc_property(
+        self, name: str, obj: t.Any, *, symbol: str = "attr"
+    ) -> Docstring:
+        ds = parse(obj.__doc__ or "")
+        description = (ds.description or "").strip()
+        short_description, long_description = self.split_description(description)
+
+        return Docstring(
+            name=name,
+            symbol=symbol,
+            label="property",
+            short_description=short_description,
+            long_description=long_description,
+            description=description,
+            deprecation=ds.deprecation,
+            returns=ds.returns,
+            raises=ds.raises,
+            examples=ds.examples,
+            many_returns=ds.many_returns,
+        )
+
+    def autodoc_attr(
+        self, attr: DocstringParam, *, symbol: str = "attr"
+    ) -> AttrDocstring:
+        if attr.type_name:
+            name = f"{attr.arg_name}: {attr.type_name}"
+        else:
+            name = attr.arg_name
+
+        description = (attr.description or "").strip()
+        short_description, long_description = self.split_description(description)
+
+        return AttrDocstring(
+            symbol=symbol,
+            name=name,
+            label="attribute",
+            short_description=short_description,
+            long_description=long_description,
+            description=description,
+        )
+
+    def get_signature(self, obj_name: str, obj: t.Any) -> str:
+        sig = inspect.signature(obj)
+        str_sig = (
+            format_signature(sig, max_width=5).replace("    self,\n", "").replace("(self)", "()")
+        )
+        return f"{obj_name}{str_sig}"
+
+    def split_description(self, description: str) -> tuple[str, str]:
+        if "\n\n" not in description:
+            return description, ""
+        head, rest = description.split("\n\n", 1)
+        return head, rest
+
+
+def format_signature(sig, *, max_width=None):
+    """Create a string representation of the Signature object.
+
+    If *max_width* integer is passed, signature will try to fit into the *max_width*.
+    If signature is longer than *max_width*, all parameters will be on separate lines.
+    """
+    result = []
+    render_pos_only_separator = False
+    render_kw_only_separator = True
+    for param in sig.parameters.values():
+        formatted = str(param)
+
+        kind = str(param.kind).lower().replace("_", "-")
+        if kind == "positional-only":
+            render_pos_only_separator = True
+        elif render_pos_only_separator:
+            # It's not a positional-only parameter, and the flag
+            # is set to 'True' (there were pos-only params before.)
+            result.append("/")
+            render_pos_only_separator = False
+
+        if kind == "variadic positional":
+            # OK, we have an '*args'-like parameter, so we won't need
+            # a '*' to separate keyword-only arguments
+            render_kw_only_separator = False
+        elif kind == "keyword-only" and render_kw_only_separator:
+            # We have a keyword-only parameter to render and we haven't
+            # rendered an '*args'-like parameter before, so add a '*'
+            # separator to the parameters list ("foo(arg1, *, arg2)" case)
+            result.append("*")
+            # This condition should be only triggered once, so
+            # reset the flag
+            render_kw_only_separator = False
+
+        result.append(formatted)
+
+    if render_pos_only_separator:
+        # There were only positional-only parameters, hence the
+        # flag was not reset to 'False'
+        result.append("/")
+
+    rendered = "({})".format(", ".join(result))
+    if max_width is not None and len(rendered) > max_width:
+        rendered = "(\n    {}\n)".format(",\n    ".join(result))
+
+    if sig.return_annotation is not inspect._empty:
+        anno = inspect.formatannotation(sig.return_annotation)
+        rendered += " -> {}".format(anno)
+
+    return rendered

writeadoc-0.1.0/src/writeadoc/blueprint/assets/css/index.css

@@ -0,0 +1,41 @@
+.page-index .hero {
+  background: rgba(var(--rgb-base), 0.4);
+}
+
+
+.headline {
+  padding: var(--space-medium);
+  padding-bottom: var(--space-large);
+}
+.headline header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-medium);
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  max-width: 60rem;
+  margin: 0 auto;
+  font-weight: 500;
+}
+.headline header h1 {
+  font-size: var(--font-size-xx-large);
+  font-weight: 900;
+  text-align: center;
+}
+.headline header p {
+  transform: skew(-4deg);
+}
+.headline header p span {
+  background-color: var(--color-base-darker);
+  padding: 0.1em;
+}
+
+@media (min-width: 64em) {
+  .headline {
+    padding: var(--space-x-large) var(--space-large);
+  }
+  .headline header h1 {
+    font-size: var(--font-size-xxx-large);
+  }
+}