From 059ac24157fa8023ade04757e4e29fdec2c5b1a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 10 Dec 2024 01:44:15 +0100 Subject: [PATCH] further additions to README & CONTRIBUTING --- CONTRIBUTING.md | 106 ++++++++++++++++++++++++++++++++++++++++++++---- README.md | 28 +++++++------ 2 files changed, 114 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cda8c844c..24e0c6a83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,13 +26,64 @@ 3. Run `npm install` 4. Start development server: `npm start` +This will be enough to work on Platform, Academy and, OpenAPI. If you want to work on entire documentation set you need to join them using Nginx. + +#### Join all repositories with Nginx + +1. Clone all the repositories +2. Run `npm start:dev` instead of `npm start` from the main repository +3. Run `npm start -- --port ` to start docusaurus instance on specific port, refer to the table for each repo port + + |Repository|Port| + |:---|:---| + |apify-docs|3000| + |apify-client-js|3001| + |apify-client-python|3002| + |apify-sdk-js|3003| + |apify-sdk-python|3004| + |apify-cli|3005| + +4. To serve them together, setup the Nginx server with the following config + + ```nginx + server { + listen 80; + server_name docs.apify.loc; + location / { + proxy_pass http://localhost:3000; + } + location /api/client/js { + proxy_pass http://localhost:3001; + } + location /api/client/python { + proxy_pass http://localhost:3002; + } + location /sdk/js { + proxy_pass http://localhost:3003; + } + location /sdk/python { + proxy_pass http://localhost:3004; + } + location /cli { + proxy_pass http://localhost:3005; + } + } + ``` + +5. Add a record to `/etc/hosts`, which maps the `docs.apify.loc` to a localhost: + + ```text + 127.0.01 docs.apify.loc + ``` + +You should be able to open https://docs.apify.loc in your browser and run all the repositories jointly as one project. ## Style guide ### Language guidelines - Use US English - Write in inclusive language -- Avoid directional language (like "left" or "right") +- Avoid directional language (like "left" or "right" or instead of "see" use "check out") - Use active voice whenever possible ### Formatting conventions @@ -41,12 +92,13 @@ - use *Bold* for UI elements - use **Italics** for emphasis - - use `code` for inline code + - use `code` for inline code, by using back-ticks (\`\`\) - use code blocks with language specification + - usd [code tabs](https://docusaurus.io/docs/markdown-features/tabs) whenever you want to include examples of implementation in more than one language 2. Documentation elements: - - Use admonitions + - Use [admonitions](https://docusaurus.io/docs/2.x/markdown-features/admonitions) to emphasize cruciac information, available admonitions are: - note - tip - info @@ -55,15 +107,25 @@ - Implement code tabs for multiple languages - Include proper metadata in front matter + Example of proper usage and formatting: + + ```text + :::note Your Title Here + + Your important message here. + + ::: + ``` + 3. Screenshots: - Use light theme when taking screenshots - Include meaningful alt texts - Use red indicators -### Metadata best practices +### Front matter metadata best practices -- Keep descriptions between 140-160 characters +- Keep descriptions between 140 and 160 characters - Avoid repetitive keywords - Use action-oriented phrasing - Exclude the word "documentation" in descriptions @@ -110,7 +172,7 @@ The API reference documentation at docs.apify.com is built directly froum our Op 1. Navigate to `apify-api/openapi/components/schemas` 2. Create a new file named after your schema 3. Define the schema structure -4. Reference schea using `$ref` in other files +4. Reference schema using `$ref` in other files Example schema @@ -127,11 +189,11 @@ properties: #### Path documentation 1. Navigate to `apify-api/openapi/paths` -2. Create YAML file following the URL structure +2. Create YAML file following the URL structure replacing `/` with `@` 3. Place path parameters in curly braces (e.g., {queueId}) 4. Add path reference to openapi.yaml -Example path structure: +Example addition to `openapi.yaml` file: ```yaml '/requests-queues': @@ -140,6 +202,26 @@ Example path structure: $ref: './paths/request-queues/request-queues@{queueId}.yaml' ``` +Example YAML file `request-queues@{queueId}.yaml` in the `paths/request-queues` folder : + +```yaml +get: + tags: + - Request Queues + summary: Get a Request Queue + operationId: requestQueues_get + description: | + You can have a markdown description here. + parameters: + responses: + '200': + '401': + x-code-samples: + - lang: PHP + source: + $ref: ../code_samples/PHP/customers/get.php +``` + #### Operation ID conventions Operation IDs must follow this format: @@ -156,6 +238,14 @@ Examples: - `/requests-queues/{queueId}` PUT -> `requestQueue_put` - `/acts/{actorId}/runs` POST -> `act_runs_post` +#### Code samples + +1. Navigate to the `openapi/code_samples` folder +2. Navigate to the `` sub-folder +3. Navigate to the `path` folder, and add ref to the code sample + +Add languages by adding new folders at the appropriate path level. + #### Submitting changes 1. Make your changes following the guidelines above diff --git a/README.md b/README.md index b342667a7..e5be5512d 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,14 @@ ## Overview -This repository is the home of Apify's documentation, available at [docs.apify.com](https://docs.apify.com/). The documentation uses [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). +This repository is the home of Apify's documentation, available at [docs.apify.com](https://docs.apify.com/). The documentation uses [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) & [Docusaurus](https://docusaurus.io/). -### Documentation structure +## Documentation structure + +Our documentation ecosystem consists of: - **Platform documentation**: Located in the [/sources](https://github.com/apify/apify-docs/tree/master/sources) directory +- **Academy**: Platform-independent courses on scraping technique. Located in the [/sources](https://github.com/apify/apify-docs/tree/master/sources) directory - **API documentation**: - **OpenAPI documentation**: [OpenAPI reference](https://docs.apify.com/api/v2) - [JavaScript/Node.js](https://docs.apify.com/api/client/js/) @@ -29,11 +32,11 @@ Before contributing, read these essential resources: Our documentation consists of these main sections: -1. **Academy**: Platform-independent courses on scraping techniques -2. **Platform**: Main documentation for using Apify as a product -3. **API**: API reference and client libraries documentation -4. **SDK**: SDK libraries documentation -5. **CLI**: Documentation for building code and platform interaction +1. **Academy**: Collection of mostly platform-independent courses on scraping techniques. +2. **Platform**: Main documentation for using Apify as a product. +3. **API**: API reference and client libraries documentation. +4. **SDK**: SDK libraries documentation. +5. **CLI**: Documentation for building code and platform interaction. ### Source Repositories @@ -44,13 +47,14 @@ Our documentation consists of these main sections: - apify-sdk-python - apify-cli -### Homepage structure +## Architecture -The homepage menu cards (in `docs/homepage_content.json`) serve three user categories: +Our documentation is built using: -1. **Beginners**: Get started, Use Actors and scrapers -2. **Experienced Users**: Reduce blocking, Use platform features -3. **Advanced Users**: Build Actors, Advanced tutorials and debugging +- **Docusaurus**: Powers our documentation platform +- **Shared Theme**: Custom `@apify/docs-theme` package +- **Automated Deployment**: CI/CD pipeline for continuous updates +- **Nginx routing**: Handles subdomain routing and redirects ## Need help