Align structure in all versions

Author: vdusek

website/docusaurus.config.js

@@ -72,19 +72,21 @@ module.exports = {
                     title: 'SDK for Python',
                     items: [
                         {
-                            to: 'docs/overview',
+                            type: 'doc',
+                            docId: 'introduction/introduction',
                             label: 'Docs',
                             position: 'left',
                             activeBaseRegex: '/docs(?!/changelog)',
                         },
                         {
-                            to: '/reference',
+                            type: 'custom-versioned-reference',
                             label: 'Reference',
                             position: 'left',
                             activeBaseRegex: '/reference',
                         },
                         {
-                            to: 'docs/changelog',
+                            type: 'doc',
+                            docId: 'changelog',
                             label: 'Changelog',
                             position: 'left',
                             activeBaseRegex: '/docs/changelog',

website/src/theme/NavbarItem/ComponentTypes.js

@@ -0,0 +1,7 @@
+import OriginalComponentTypes from '@theme-original/NavbarItem/ComponentTypes';
+import VersionedReferenceNavbarItem from './VersionedReferenceNavbarItem';
+
+export default {
+    ...OriginalComponentTypes,
+    'custom-versioned-reference': VersionedReferenceNavbarItem,
+};

website/src/theme/NavbarItem/VersionedReferenceNavbarItem.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import { useDocsVersionCandidates } from '@docusaurus/plugin-content-docs/client';
+import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+
+/* eslint-disable react/prop-types */
+export default function VersionedReferenceNavbarItem({ docsPluginId, ...props }) {
+    const [version] = useDocsVersionCandidates(docsPluginId);
+
+    // Latest version → /reference, "current" (next) → /reference/next, others → /reference/{name}
+    let to = '/reference';
+    if (!version.isLast) {
+        to = `/reference/${version.name === 'current' ? 'next' : version.name}`;
+    }
+
+    return <DefaultNavbarItem {...props} to={to} />;
+}

website/versioned_docs/version-1.7/01-introduction/index.mdx

@@ -0,0 +1,50 @@
+---
+id: introduction
+title: Overview
+sidebar_label: Overview
+slug: /overview
+description: 'The official library for creating Apify Actors in Python, providing tools for web scraping, automation, and data storage integration.'
+---
+
+The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python.
+
+```python
+from apify import Actor
+from bs4 import BeautifulSoup
+import requests
+
+async def main():
+    async with Actor:
+        actor_input = await Actor.get_input()
+        response = requests.get(actor_input['url'])
+        soup = BeautifulSoup(response.content, 'html.parser')
+        await Actor.push_data({ 'url': actor_input['url'], 'title': soup.title.string })
+```
+
+## What are Actors?
+
+Actors are serverless cloud programs that can do almost anything a human can do in a web browser. They can do anything from small tasks such as filling in forms or unsubscribing from online services, all the way up to scraping and processing vast numbers of web pages.
+
+Actors can be run either locally, or on the [Apify platform](https://docs.apify.com/platform/), where you can run them at scale, monitor them, schedule them, and even publish and monetize them.
+
+If you're new to Apify, learn [what is Apify](https://docs.apify.com/platform/about) in the Apify platform documentation.
+
+## Quick start
+
+To create and run Actors through Apify Console, see the [Console documentation](https://docs.apify.com/academy/getting-started/creating-actors#choose-your-template). For creating and running Python Actors locally, refer to the [quick start guide](./quick-start).
+
+Explore the Guides section in the sidebar for a deeper understanding of the SDK's features and best practices.
+
+## Installation
+
+The Apify SDK for Python requires Python version 3.8 or above. It is typically installed when you create a new Actor project using the [Apify CLI](https://docs.apify.com/cli). To install it manually in an existing project, use:
+
+```bash
+pip install apify
+```
+
+:::note API client alternative
+
+If you need to interact with the Apify API programmatically without creating Actors, use the [Apify API client for Python](https://docs.apify.com/api/client/python) instead.
+
+:::

website/versioned_docs/version-1.7/01-introduction/quick-start.mdx

@@ -0,0 +1,140 @@
+---
+id: quick-start
+title: Quick start
+sidebar_label: Quick start
+description: 'Get started with the Apify SDK for Python by creating your first Actor and learning the basics.'
+---
+
+Learn how to create and run Actors using the Apify SDK for Python.
+
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+## Step 1: Create Actors
+
+To create and run Actors through Apify Console, see the [Console documentation](https://docs.apify.com/academy/getting-started/creating-actors#choose-your-template).
+
+To create a new Apify Actor on your computer, you can use the [Apify CLI](https://docs.apify.com/cli), and select one of the [Python Actor templates](https://apify.com/templates?category=python).
+
+For example, to create an Actor from the "[beta] Python SDK" template, you can use the [`apify create` command](https://docs.apify.com/cli/docs/reference#apify-create-actorname).
+
+```bash
+apify create my-first-actor --template python-start
+```
+
+This will create a new folder called `my-first-actor`, download and extract the "Getting started with Python" Actor template there, create a virtual environment in `my-first-actor/.venv`, and install the Actor dependencies in it.
+
+## Step 2: Run Actors
+
+To run the Actor, you can use the [`apify run` command](https://docs.apify.com/cli/docs/reference#apify-run):
+
+```bash
+cd my-first-actor
+apify run
+```
+
+This command:
+
+- Activates the virtual environment in `.venv` (if no other virtual environment is activated yet)
+- Starts the Actor with the appropriate environment variables for local running
+- Configures it to use local storages from the `storage` folder
+
+The Actor input, for example, will be in `storage/key_value_stores/default/INPUT.json`.
+
+## Step 3: Understand Actor structure
+
+All Python Actor templates follow the same structure.
+
+The `.actor` directory contains the [Actor configuration](https://docs.apify.com/platform/actors/development/actor-config), such as the Actor's definition and input schema, and the Dockerfile necessary to run the Actor on the Apify platform.
+
+The Actor's runtime dependencies are specified in the `requirements.txt` file, which follows the [standard requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/).
+
+The Actor's source code is in the `src` folder. This folder contains two important files:
+
+- `main.py` - which contains the main function of the Actor
+- `__main__.py` - which is the entrypoint of the Actor package, setting up the Actor [logger](../concepts/logging) and executing the Actor's main function via [`asyncio.run()`](https://docs.python.org/3/library/asyncio-runner.html#asyncio.run).
+
+<Tabs>
+    <TabItem value="main.py" label="main.py" default>
+        <CodeBlock language="python">{
+`from apify import Actor
+${''}
+async def main():
+    async with Actor:
+        Actor.log.info('Actor input:', await Actor.get_input())
+        await Actor.set_value('OUTPUT', 'Hello, world!')`
+        }</CodeBlock>
+    </TabItem>
+    <TabItem value="__main__.py" label="__main.py__">
+        <CodeBlock language="python">{
+`import asyncio
+import logging
+${''}
+from apify.log import ActorLogFormatter
+${''}
+from .main import main
+${''}
+handler = logging.StreamHandler()
+handler.setFormatter(ActorLogFormatter())
+${''}
+apify_logger = logging.getLogger('apify')
+apify_logger.setLevel(logging.DEBUG)
+apify_logger.addHandler(handler)
+${''}
+asyncio.run(main())`
+        }</CodeBlock>
+    </TabItem>
+</Tabs>
+
+If you want to modify the Actor structure, you need to make sure that your Actor is executable as a module, via `python -m src`, as that is the command started by `apify run` in the Apify CLI. We recommend keeping the entrypoint for the Actor in the `src/__main__.py` file.
+
+## Step 4: Add dependencies {#adding-dependencies}
+
+Adding dependencies into the Actor is simple.
+
+First, add them in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder.
+
+Then activate the virtual environment in `.venv`:
+
+<Tabs groupId="operating-systems">
+    <TabItem value="unix" label="Linux / macOS" default>
+        <CodeBlock language="bash">{
+`source .venv/bin/activate`
+        }</CodeBlock>
+    </TabItem>
+    <TabItem value="win" label="Windows">
+        <CodeBlock language="powershell">{
+`.venv\\Scripts\\activate`
+        }</CodeBlock>
+    </TabItem>
+</Tabs>
+
+Then install the dependencies:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+## Next steps
+
+### Guides
+
+To see how you can integrate the Apify SDK with some of the most popular web scraping libraries, check out our guides for working with:
+
+- [Requests or HTTPX](../guides/requests-and-httpx)
+- [Beautiful Soup](../guides/beautiful-soup)
+- [Playwright](../guides/playwright)
+- [Selenium](../guides/selenium)
+- [Scrapy](../guides/scrapy)
+
+### Concepts
+
+To learn more about the features of the Apify SDK and how to use them, check out the Concepts section in the sidebar, especially the guides for:
+
+- [Actor lifecycle](../concepts/actor-lifecycle)
+- [Working with storages](../concepts/storages)
+- [Handling Actor events](../concepts/actor-events)
+- [How to use proxies](../concepts/proxy-management)