From 367c63ef1d2541099e3a4c2cd4f4c1a646be2e91 Mon Sep 17 00:00:00 2001 From: Agnieszka Marzec <97166305+agnieszka-m@users.noreply.github.com> Date: Thu, 22 Dec 2022 15:53:48 +0100 Subject: [PATCH] Update readme (#3744) --- docs/README.md | 57 +++++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/README.md b/docs/README.md index d44430b26..a059475b1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,41 +1,36 @@ # :ledger: Looking for the docs? -Haystack's documentation website can be found at https://haystack.deepset.ai/overview/intro +You can find Haystack's documentation at https://docs.haystack.deepset.ai/. # :computer: How to update docs? -## Overview and Usage +## Overview, Components, Pipeline Nodes, and Guides -We moved the Overview and Usage docs to the [haystack-website](https://github.com/deepset-ai/haystack-website) repository. You will find the docs in the folder `docs`. Please make sure to only edit the latest version of the docs. We will release the docs together with the Haystack version. -We are open for contributions to our documentation. Please make sure to check our [Contribution Guidelines](https://github.com/deepset-ai/haystack/blob/main/CONTRIBUTING.md). You will find a step by step introduction to our docs [here](https://github.com/deepset-ai/haystack-website/tree/source). +You can find these docs on the Haystack Docs page: https://docs.haystack.deepset.ai/docs/get_started. If you want to contribute, and we welcome every contribution, do the following: +1. Make sure you're on the right version (check the version expanding list in the top left corner). +2. Use the "Suggest Edits" link you can find in the top right corner of every page. +3. Suggest a change right in the docs and click **Submit Suggested Edits**. +4. Optionally, leave us a comment and submit your change. + +Once we take care of it, you'll get an email telling you the change's been merged, or not. If not, we'll give you the reason why. + +Make sure to check our [Contribution Guidelines](https://github.com/deepset-ai/haystack/blob/main/CONTRIBUTING.md). ## Tutorials -The Tutorials live in the folder `tutorials`. -They are created as colab notebooks which can be used by users to explore new haystack features. -To include tutorials into the documentation website, markdowns files need to be generated from the notebook. -There is a Github action that regenerates the markdown file with each commit. -This can also be done manually by running the script `/docs/_src/tutorials/tutorials/convert_ipynb.py`. -Furthermore, plaese make sure to update the `headers.py` file with headers for the new tutorials. -These headers are important for the docs website workflow. -After the markdown files are generated successfully, you can raise a PR. -We will review it and as soon as the markdown file is merged to main, it will automatically be added to the website. -Please follow the steps described [here](https://github.com/deepset-ai/haystack-website/tree/source) under `Tutorial & Reference Docs`. +The Tutorials live in a separate repo: https://github.com/deepset-ai/haystack-tutorials. For instructions on how to contribute to tutorials, see [Contributing to Tutorials](https://github.com/deepset-ai/haystack-tutorials/blob/main/Contributing.md#contributing-to-haystack-tutorials). ## API Reference -We use Pydoc-Markdown to create markdown files from the docstrings in our code. -There is a Github Action that regenerates the API pages with each commit. +We use Pydoc-Markdown to create Markdown files from the docstrings in our code. There is a Github Action that regenerates the API pages with each commit. +If you want to generate a new Markdown file for a new Haystack module, create a `.yml` file in `docs/src/api/api` which configures how Pydoc-Markdown will generate the page and commit it to main. -If you want to generate a new markdown file for a new haystack module, -please create a `.yml` file in `docs/src/api/api` which configures how Pydoc-Markdown will generate the page. -To include it into the docs website, push it to main and follow the steps described -[here](https://github.com/deepset-ai/haystack-website/tree/source) under `Tutorial & Reference Docs`. +All the updates to doctrings get pushed to documentation when you commit to the main branch. ### Configuration -Pydoc will read the configuration from a `.yml` file which is located under `/haystack/docs/_src/api/pydoc`. Our files contains three main sections: +Pydoc will read the configuration from a `.yml` file which is located under `/haystack/docs/_src/api/pydoc`. Our files contain three main sections: - **loader**: A list of plugins that load API objects from python source files. - **type**: Loader for python source files @@ -47,10 +42,16 @@ Pydoc will read the configuration from a `.yml` file which is located under `/ha - **documented_only**: Only documented API objects - **do_not_filter_modules**: Do not filter module objects - **skip_empty_modules**: Skip modules without content -- **renderer**: A plugin that produces the output files. - - **type**: Define the renderer which you want to use. We are using the Markdown renderer as it can be configured in very detail. - - **descriptive_class_title**: Remove the word "Object" from class titles. - - **descriptive_module_title**: Adding the word “Module” before the module name - - **add_method_class_prefix**: Add the class name as a prefix to method names - - **add_member_class_prefix**: Add the class name as a prefix to member names - - **filename**: file name of the generated file \ No newline at end of file +- **renderer**: A plugin that produces the output files. We use a custom ReadmeRenderer based on the Markdown renderer. It makes sure the Markdown files comply with ReadMe requirements. + - **type**: Define the renderer which you want to use. We are using the ReadmeRenderer to make sure the files display properly in ReadMe. + - **excerpt**: Add a short description of the page. It shows up right below the page title. + - **category**: This is the ReadMe category ID to make sure the doc lands in the right section of Haystack docs. + - **title**: The title of the doc as it will appear on the website. Make sure you always add "API" at the end. + - **slug**: The page slug, each word should be separated with a dash. + - **order**: Pages are ordered alphabetically. This defines where in the TOC the page lands. + - markdown: + - **descriptive_class_title**: Remove the word "Object" from class titles. + - **descriptive_module_title**: Adding the word “Module” before the module name. + - **add_method_class_prefix**: Add the class name as a prefix to method names. + - **add_member_class_prefix**: Add the class name as a prefix to member names. + - **filename**: File name of the generated file, use underscores to separate each word.