docs: Fix code sample on home page (#913)

### Description

- Fix code sample on home page and move it to a separate Python file.
- Fix code sample in `docs/introduction/07_saving_data.mdx` and move it
to a separate Python file.
- Rm old pydoc-markdown scripts (they live in a [separate
repository](https://github.com/apify/docusaurus-plugin-typedoc-api/tree/master/packages/plugin/python-scripts/docspec-gen)
now).

### Issues

- Closes: #912

### Testing

- Docs were rendered locally.

### Checklist

- [x] CI passed

Author: vdusek

Makefile

@@ -1,6 +1,6 @@
 .PHONY: clean install-dev build publish-to-pypi lint type-check unit-tests unit-tests-cov integration-tests format check-code build-api-reference run-docs
 
-DIRS_WITH_CODE = src tests docs
+DIRS_WITH_CODE = src tests docs website
 
 # This is default for local testing, but GitHub workflows override it to a higher value in CI
 INTEGRATION_TESTS_CONCURRENCY = 1

docs/introduction/07_saving_data.mdx

@@ -7,31 +7,22 @@ import ApiLink from '@site/src/components/ApiLink';
 import CodeBlock from '@theme/CodeBlock';
 
 import FinalCodeExample from '!!raw-loader!./code/07_final_code.py';
+import FirstCodeExample from '!!raw-loader!./code/07_first_code.py';
 
 A data extraction job would not be complete without saving the data for later use and processing. You've come to the final and most difficult part of this tutorial so make sure to pay attention very carefully!
 
 ## Save data to the dataset
 
-Crawlee provides a <ApiLink to="class/Dataset">`Dataset`</ApiLink> class, which acts as an abstraction over tabular storage, making it useful for storing scraping results. First, add the following import to the top of your file:
+Crawlee provides a <ApiLink to="class/Dataset">`Dataset`</ApiLink> class, which acts as an abstraction over tabular storage, making it useful for storing scraping results. To get started:
 
-```python
-from crawlee.playwright_crawler import PlaywrightCrawler, PlaywrightCrawlingContext
-from crawlee.storages.dataset import Dataset
-
-# ...
-```
+- Add the necessary imports: Include the <ApiLink to="class/Dataset">`Dataset`</ApiLink> and any required crawler classes at the top of your file.
+- Create a Dataset instance: Use the asynchronous <ApiLink to="class/Dataset#open">`Dataset.open`</ApiLink> constructor to initialize the dataset instance within your crawler's setup.
 
-Next, under the section where you create an instance of your crawler, create an instance of the dataset using the asynchronous constructor  <ApiLink to="class/Dataset#open">`Dataset.open`</ApiLink>:
+Here's an example:
 
-```python
-# ...
-
-async def main() -> None:
-    crawler = PlaywrightCrawler()
-    dataset = await Dataset.open()
-
-    # ...
-```
+<CodeBlock className="language-python">
+    {FirstCodeExample}
+</CodeBlock>
 
 Finally, instead of logging the extracted data to stdout, we can export them to the dataset:
 

docs/introduction/code/07_first_code.py

@@ -0,0 +1,16 @@
+from crawlee.crawlers import PlaywrightCrawler, PlaywrightCrawlingContext
+from crawlee.storages import Dataset
+
+# ...
+
+
+async def main() -> None:
+    crawler = PlaywrightCrawler()
+    dataset = await Dataset.open()
+
+    # ...
+
+    @crawler.router.default_handler
+    async def request_handler(context: PlaywrightCrawlingContext) -> None:
+        ...
+        # ...

pyproject.toml

@@ -153,7 +153,7 @@ indent-style = "space"
     "T20",     # flake8-print
     "TRY301",  # Abstract `raise` to an inner function
 ]
-"**/{docs}/**" = [
+"**/{docs,website}/**" = [
     "D",      # Everything from the pydocstyle
     "INP001", # File {filename} is part of an implicit namespace package, add an __init__.py
     "F841",   # Local variable {variable} is assigned to but never used
@@ -192,7 +192,7 @@ timeout = 1200
 python_version = "3.9"
 plugins = ["pydantic.mypy"]
 exclude = ["project_template"]
-files = ["src", "tests"]
+files = ["src", "tests", "docs", "website"]
 check_untyped_defs = true
 disallow_incomplete_defs = true
 disallow_untyped_calls = true
@@ -215,7 +215,7 @@ ignore_missing_imports = true
 [tool.basedpyright]
 pythonVersion = "3.9"
 typeCheckingMode = "standard"
-include = ["src", "tests", "docs"]
+include = ["src", "tests", "docs", "website"]
 
 [tool.coverage.report]
 exclude_lines = [

website/generate_module_shortcuts.py

@@ -1,18 +1,26 @@
 #!/usr/bin/env python3
 
+from __future__ import annotations
+
 import importlib
 import inspect
 import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from types import ModuleType
 
 
-def get_module_shortcuts(module, parent_classes=None):
-    """Traverse a module and its submodules, and if some class is present in both a module and its submodule, register a shortcut."""
+def get_module_shortcuts(module: ModuleType, parent_classes: list | None = None) -> dict:
+    """Traverse a module and its submodules to identify and register shortcuts for classes."""
     shortcuts = {}
 
     if parent_classes is None:
         parent_classes = []
+
     parent_module_name = '.'.join(module.__name__.split('.')[:-1])
     module_classes = []
+
     for classname, cls in inspect.getmembers(module, inspect.isclass):
         module_classes.append(cls)
         if cls in parent_classes:
@@ -25,16 +33,15 @@ def get_module_shortcuts(module, parent_classes=None):
     return shortcuts
 
 
-def resolve_shortcuts(shortcuts):
+def resolve_shortcuts(shortcuts: dict) -> None:
     """Resolve linked shortcuts.
 
-    For example, if there are shortcuts A -> B and B -> C,
-    resolve them to A -> C.
+    For example, if there are shortcuts A -> B and B -> C, resolve them to A -> C.
     """
     for source, target in shortcuts.items():
         while target in shortcuts:
             shortcuts[source] = shortcuts[target]
-            target = shortcuts[target]
+            target = shortcuts[target]  # noqa: PLW2901
 
 
 shortcuts = {}
@@ -43,7 +50,7 @@ def resolve_shortcuts(shortcuts):
         module = importlib.import_module(module_name)
         module_shortcuts = get_module_shortcuts(module)
         shortcuts.update(module_shortcuts)
-    except ModuleNotFoundError:
+    except ModuleNotFoundError:  # noqa: PERF203
         pass
 
 resolve_shortcuts(shortcuts)