diff --git a/_includes/more-resources-contributor-guide.md b/_includes/more-resources-contributor-guide.md deleted file mode 100644 index 3b0a43ea..00000000 --- a/_includes/more-resources-contributor-guide.md +++ /dev/null @@ -1,6 +0,0 @@ -For additional information, try these sources. - -- [Frequently Asked Questions](/weaviate/more-resources/faq) -- [Weaviate Community Forum](https://forum.weaviate.io/) -- [Knowledge base of old issues](https://github.com/weaviate/weaviate/issues?utf8=%E2%9C%93&q=label%3Abug) -- [Weaviate slack channel](https://weaviate.io/slack) diff --git a/docs/contributor-guide/contextionary/_category_.json b/docs/contributor-guide/contextionary/_category_.json deleted file mode 100644 index 9a71da7b..00000000 --- a/docs/contributor-guide/contextionary/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contextionary", - "position": 5 -} diff --git a/docs/contributor-guide/contextionary/classification-benchmarks.md b/docs/contributor-guide/contextionary/classification-benchmarks.md deleted file mode 100644 index d3a1e5d1..00000000 --- a/docs/contributor-guide/contextionary/classification-benchmarks.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Classification Benchmarks -sidebar_position: 1 -image: og/contributor-guide/contextionary.jpg -# tags: ['contributor-guide'] ---- - -## Model Version Details - -Benchmarks on this page refer to a specific model version, details about -each version are contained here: - -| model version | training algo | input sources | input size | dimensions | window size | release status | -|--|--|--|--|--|--|--| -| en0.14.0 | GloVe | Wiki | `~14G` | 600 | 15 | **released** | -| en0.16.0 | GloVe | Wiki, CommonCrawl | `~1000G` | 300 | 15 | **released** | -| en0.17.0 | fasttext | Wiki | `~14G` | 300 | 15 | *not released (yet)* | -| en0.17.1 | fasttext | Wiki | `~14G` | 300 | 5 | *not released (yet)* | -| en0.17.2 | fasttext | Wiki, CommonCrawl | `~1000G` | 300 | 15 | training aborted! | -| en0.17.3 | fasttext | Wiki, CommonCrawl | `~100G` | 300 | 15 | *not released (yet)* | - -## Benchmarks (KNN) - -### Enron Emails (Subset `kaminski-v`) - -* Source Repo: `weaviate/enron-email-classification` -* Current best: `en0.14.0` at `k=1` - -| contextionary | dimensions | k=1 | k=3 | k=5 | k=8 | k=13 | k=21 | -|---------------|------------|-----|-----|-----|-----|------|------| -| en0.14.0-v0.4.9 | 600 | **74%** | 72% | 71% | 70% | 67% | 63% | -| en0.16.0-v0.4.9 | 300 | 72% | 70% | 69% | 69% | 65% | 64% | -| en0.17.0-v0.4.15 | 300 | 68% | 68% | 67% | 64% | 63% | 60% | -| en0.17.1-v0.4.15 | 300 | 70% | 68% | 68% | 66% | 64% | 62% | -| en0.17.3-v0.4.15 | 300 | 72% | 70% | 70% | 69% | 66% | 64% | - -### 20 Newsgroups - -* Size: 60 per category -* Source Repo `weaviate/20news-classification` - -#### Main Category (6 Categories) - -* Current best: `en0.17.3` at `k=5` - -| contextionary | dimensions | k=1 | k=3 | k=5 | k=8 | k=13 | k=21 | -|---------------|------------|-----|-----|-----|-----|------|------| -| en0.14.0-v0.4.15 | 600 | 76% | 73% | 72% | 74% | 74% | 70% | -| en0.16.0-v0.4.15 | 300 | 83%| 82% | 80% | 82% | 82% | 82% | -| en0.17.0-v0.4.15 | 300 | 78% | 80% | 77% | 77% | 73% | 72% | -| en0.17.1-v0.4.15 | 300 | 77% | 77% | 78% | 77% | 73% | 73% | -| en0.17.3-v0.4.15 | 300 | 83% | 84%| **85%** | 82% | 81% | 80% | - -#### Fine Category (20 Categories) - -* Current best: `en0.17.3` at `k=1` - -| contextionary | dimensions | k=1 | k=3 | k=5 | k=8 | k=13 | k=21 | -|---------------|------------|-----|-----|-----|-----|------|------| -| en0.14.0-v0.4.15 | 600 | 57% | 53% | 53% | 50% | 48% | 46% | -| en0.16.0-v0.4.15 | 300 | 62%| 60% | 57% | 60% | 61% | 59% | -| en0.17.0-v0.4.15 | 300 | 57% | 57% | 56% | 56% | 56% | 51% | -| en0.17.1-v0.4.15 | 300 | 56% | 54% | 55% | 58% | 54% | 53% | -| en0.17.3-v0.4.15 | 300 | **66%** | 64% | 64% | 61% | 62% | 61% | - -## Benchmarks (contextual) - -### 20 Newsgroups - -* Size: 60 per category -* Source Repo: `weaviate/20news-classification` -* *Warning: Take these results (20-news **contextual**) with a grain of salt, - they are not currently testing the best possible hyper-parameters, but just a - specific configuration that worked well in the past. TODO: Improve benchmark - to test various hyper-parameters* - -#### Main Category (6 Categories) - -* Current best: `en0.14.0` - -| contextionary | dimensions | result | -|---------------|------------|-----| -| en0.14.0-v0.4.15 | 600 | **54%** | -| en0.16.0-v0.4.15 | 300 | 50% | -| en0.17.0-v0.4.15 | 300 | 50% | -| en0.17.1-v0.4.15 | 300 | 50% | -| en0.17.3-v0.4.15 | 300 | 50% | - -#### Fine Category (20 Categories) - -* Current best: `en0.16.0` - -| contextionary | dimensions | result | -|---------------|------------|-----| -| en0.14.0-v0.4.15 | 600 | 44% | -| en0.16.0-v0.4.15 | 300 | **56%** | -| en0.17.0-v0.4.15 | 300 | 44% | -| en0.17.0-v0.4.15 | 300 | 43% | -| en0.17.3-v0.4.15 | 300 | 50% | - - -## More Resources - -import ContributorGuideMoreResources from '/_includes/more-resources-contributor-guide.md'; - - - -## Questions and feedback - -import DocsFeedback from '/_includes/docs-feedback.mdx'; - - \ No newline at end of file diff --git a/docs/contributor-guide/contextionary/index.md b/docs/contributor-guide/contextionary/index.md deleted file mode 100644 index 851fe398..00000000 --- a/docs/contributor-guide/contextionary/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Contextionary -sidebar_position: 0 -image: og/contributor-guide/contextionary.jpg -# tags: ['contextionary'] ---- - -The Contextionary is the pretrained language model that can come with Weaviate. It gives context and semantics to the language use in the dataset. You can read more about what the Contextionary (c11y) is [here](/weaviate/modules/text2vec-contextionary.md). - -The Contextionary can be found on [GitHub](https://github.com/weaviate/contextionary), but note that this is not intended for stand-alone use. Find benchmarks of this trained language model on the [Classification benchmarks](/contributor-guide/contextionary/classification-benchmarks.md) page. diff --git a/docs/contributor-guide/getting-started/_category_.json b/docs/contributor-guide/getting-started/_category_.json deleted file mode 100644 index 877a378f..00000000 --- a/docs/contributor-guide/getting-started/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Getting Started", - "position": 2 -} diff --git a/docs/contributor-guide/getting-started/commit-guidelines.md b/docs/contributor-guide/getting-started/commit-guidelines.md deleted file mode 100644 index 5ad13d8e..00000000 --- a/docs/contributor-guide/getting-started/commit-guidelines.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Commit Guidelines -description: Commit Guidelines for Contributing to Weaviate -sidebar_position: 7 -image: og/contributor-guide/getting-started.jpg -# tags: ['contributor-guide'] ---- -## Introduction - -When collaborating with git, each commit provides a frozen snapshot of work for you or others to review. It is good practice is to create a commit per "logical change", so that each commit represents a "unit" of work done. - -You might have heard that changing one variable at a time during scientific experimentation makes the output and therefore its effect easier to interpret. In the same way, creating one commit per logical change or theme helps the maintainer understand and review your work. It will also create logical, isolated checkpoints from which changes can be integrated into other branches. - -Another big part of creating good commits is writing good commit messages. Writing good commit messages helps the whole team. It will help others understand what you have done, and help you become a better software developer. - -## Tips on writing good commit messages - -* Be concise. This will speed up review, and thus the feedback loop. -* Be precise and specific, as to help people searching or navigating through the commit history. - -Examples of **good commit messages** include: - -* `add sitemap plugin to the website` -* `update ruby version to 2.7.5` -* `update version number dynamically` -* `fix typo in introduction to user guide` - -Example of **bad commit messages**, with reasons, include: - -* `Fixed typo in the doc` (which doc?) -* `Changed CSS style` (why? how?) -* `modified README.md` (why? how?) -* `Added search feature in the docs` (which files? how?) - -Note: Some people prefer to use an imperative present tense in commit messages. There is [no consensus on this](https://stackoverflow.com/questions/3580013/should-i-use-past-or-present-tense-in-git-commit-messages), and is likely to be situational. The most important thing is to ensure that the substance of the changes are clear in the message. In other words, [don't do this](https://xkcd.com/1296/) 😉. - -Taking time to write a consistent, specific, and accurate git commit messages will help the reader, who will thank you for it. This will often include your future self! So think of it as an investment where the return is based primarily on clarity of communication. - -## Example commit message structure - -One way to write good commit messages is to use a template structure. One structure would be to think of it like a GitHub issue, with three parts: - -* Summary line -* Issue reference -* Description - -### Summary Line: - -Summary line are used throughout git. So try not to exceed 50 characters (while being informative), and put a blank line afterwards before the message body. This will help git parse the summary line correctly. - -Example: - -```text -add new blog "Why vector search is so fast" -``` - -### Issue reference - -* If the commit fixes an issue, reference that issue using `#` symbol: "This PR fixes: #ISSUE_NUMBER.". - -* The issue reference will add the commit link to the issue automatically. - -Example: - -```text -Why: -This PR fixes: #123 -``` - -### Description - -Every repository has a [pull request template](https://github.com/weaviate/docs/blob/main/.github/PULL_REQUEST_TEMPLATE.md) with a specific set of headers that you can use to write the body of commit messages. You can modify this template at the time of making a pull request and exclude the parts which is not necessary. - -Example: - -```text -What's being changed: - -This pull request adds blog page feature to the documentation website, -where people can read about Weaviate's latest releases. -Blogs can be updated by adding markdown files to `_posts/blog/` folder. - -Type of change: - -[] Bug fix (non-breaking change which fixes an issue) -[x] Feature or enhancements (non-breaking change which adds functionality) -[] Documentation updates (non-breaking change which updates documents) - -How Has This Been Tested? - -This has been tested locally by building and running the site -```text - -* Each description line must be no more than 75 characters long (there is no limit on number of lines). - -* You should explain why the changes were made. This is especially important for complex, non-self-explanatory changes. - -* You must select the type of change you made. Remove the irrelevant options from the list by putting a `x` in the square brackets in front of the type of change. - -* The commit message is primarily for your and others' benefit, and they should be able to understand it both now and in the future. - -* If the summary is self-explanatory, you can omit writing the description. - -* Tests are essential, and you should describe how you tested your changes locally and whether you discovered any other breaking changes. -``` - -## More Examples -We include additional git commit message examples below: - -* For a bugfix - -```text -fix: static version number on quickstart page - -Why: -This PR fixes: #103 - -What's being changed: - -In quick-start.md file of every version, the version present in the example -didn't match the configuration. This problem was caused due to variable -weaviate_version which had hard-coded value of v1.12.1. This caused all -the pages to show fix version. - -Workaround for this was to include a this tag, which identified current -version of the page and call the variable current_page_version in front -of version key. - -Type of change: - -[x] Bug fix (non-breaking change which fixes an issue) - -How Has This Been Tested? - -This has been tested locally by building and running the site -``` - -* For a new feature - -```text -add copy to clipboard functionality to docs - -What's being changed: - -The documentation site contains a large number of code snippets that we -need to manually copy. The addition of a copy to clipboard functionality -will make it easier to copy the codes and reuse them. - -Type of change: - -[x] Feature or enhancements (non-breaking change which adds functionality) - -How Has This Been Tested? - -This has been tested locally by building and running the site -``` - -* For documentation changes - -```text -fix typo in getting started docker compose example - -What's being changed: - -This PR corrects a typo in docs/weaviate/current/getting-started/ -installation.md, where the docker-compose.yml example lacks a '. The -docker-compose.yml file previously did not work, but it now does. - -Type of change: - -[x] Documentation updates (non-breaking change which updates documents) - -How Has This Been Tested? - -This has been tested locally by building and running the site -``` diff --git a/docs/contributor-guide/getting-started/git-and-github.md b/docs/contributor-guide/getting-started/git-and-github.md deleted file mode 100644 index 3858f7a7..00000000 --- a/docs/contributor-guide/getting-started/git-and-github.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: Git and GitHub guide -description: Git and GitHub Guide for Weaviate -sidebar_position: 6 -image: og/contributor-guide/getting-started.jpg -# tags: ['contributor-guide'] ---- -## Introduction - -Git and GitHub are indispensable tools for working with open-source communities. - -So we prepared a guide on using git and GitHub to help you contribute to Weaviate. If you are relatively new to working on open-source projects, you may find this section helpful. - -If you are new to git/GitHub, you can go through this section like a tutorial and follow along. Alternatively, you can treat it as a reference and jump to the relevant section. The commands shown below are shell commands. - -## Contributing to Weaviate using git and GitHub - -There are four major GitHub repositories of Weaviate, any of which you can contribute to. This includes: - -* [Weaviate](https://github.com/weaviate/weaviate) - Weaviate's "core" codebase -* [Docs](https://github.com/weaviate/docs) - official Weaviate documentation -* [Weaviate Examples](https://github.com/weaviate/weaviate-examples) - apps built using Weaviate -* [Awesome Weaviate](https://github.com/weaviate/awesome-weaviate) - list of examples and tutorials on how to use Weaviate - -Generally speaking, the process to contribute using git and GitHub goes like this: - -- Identify the right repository to contribute to. Then: - - To report a bug or suggest an enhancement, [open an issue](#report-an-issue) - - To contribute to the code base or the documentation: - - [Fork the right repository on GitHub](#fork-the-repository) - - [Clone the forked repository](#make-clone-a-local-copy) - - [Create a new branch and make changes](#create-a-new-branch-to-work-on) - - [Push your changes and create a pull request](#pull-request-process) - -Here is some information on working with git and GitHub. - -## Git - -Git is a version control tool which keeps track of the changes you make to files, allowing you to go back to previous versions if necessary and keeping a record of what has been done. - -Each set of tracked files is called a "repository", or a "repo". Each repo is typically contained in a directory. - -You need to install Git on your computer before you can use it. If it's already installed, updating to the most recent version is probably a good idea. Read more about **installing git** [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - -Once you have installed git, you can run commands like `git pull`, `git commit` or `git push` on the command line. This mode of activity is also called the git command-line interface (CLI). - -## Using GitHub - -[GitHub](https://github.com/) is a website and cloud-based service for collaborating using git repositories. - -To be clear, you do not need a GitHub account to use Weaviate. But you will need one to contribute code or documentation to open source projects hosted on GitHub, which includes Weaviate. - -You can create a GitHub account [here](https://github.com/join). - -## Git vs. GitHub - -Git is a version control tool. GitHub is an online platform that serves as a remote repository for git projects. - -You can just use git on your local machine, but using a remote repository such as GitHub enables efficient collaboration with other team members. - -Now, let's take a look at how we can use git and GitHub to contribute to Weaviate. - -## Report an issue - -GitHub allows creation and tracking of "issues". These are typically used to manage bugs or feature requests. To create an "issue" on GitHub, go to the issue tab in the relevant repository, and click "New issue." - -![new issue](/img/contributor-guide/getting-started/new_issue.png) - -There are several templates available, such as documentation feedback, and bug reporting. If you want to create your own custom issue, go to the bottom left of the issue list box and click "Open a blank issue." - -![issue templates](/img/contributor-guide/getting-started/issue_templates.png) - -### Example: Create a new issue - -![create a new issue](/img/contributor-guide/getting-started/new_issue_temp.png) - -Fill out each field based on the questions and guidance provided. - -## Work with a fork - -To work on a Weaviate repository, we recommend that you fork it first and then work on it. - -> A **fork** is your own copy of someone else's repository. Forks let you make changes to a project without affecting the original repository. You can fetch updates from or submit changes to the original repository with pull requests. - -### Fork the repository - -* To create a fork, go to the relevant GitHub repository and click the `Fork` button. This will create a copy of the repository (i.e. a fork) under your account. - -![fork repo](/img/contributor-guide/getting-started/fork.png) - -The original repository is typically called the "upstream" repo. - -### Make (clone) a local copy - -* Now we need to `clone` your new repo. This will place a local copy of the repository on your machine so that you can make changes. Go to GitHub, and copy the URI of the repository. - -![clone repo](/img/contributor-guide/getting-started/clone.png) - -Using this URI, type into your shell: - -```shell -git clone git@github.com:/weaviate.git -``` - -Where `git@github.com:/weaviate.git` is the URI you copied. - -**Note:** ("weaviate" is used as the example repo. Make sure to cite the particular repository you are contributing to (for example, "docs") - -After cloning the repository from GitHub, use the `change directory` command to navigate to the cloned folder. - -```shell -cd weaviate -``` - -Now you have a complete local copy of the repository! Here are some tips now on how to go about making changes to the repository, so that you can (hopefully) get them incorporated. - -## Create a new branch to work on - -Do not change files on a main branch, even if it is on your fork. - -It's best practice to create a new branch for each set of changes such as a new feature or bugfix. The reason is that it isolates each set of changes from the `main` branch so that each Pull Request can also be evaluated and managed independently. - -Create a new branch with a simple informative name. For example: - -- For enhancements use `feature/issue#` or `feature/nameOfFeature` -- For bugs use `bug/issue#` or `bug/nameOfBug` - -To work with a new branch you can run either - -```shell -git branch feature/newPage #create a new branch -git checkout feature/newPage #checkout on created branch -``` - -Or - -```shell -git checkout -b feature/newPage -``` - -**Note:** -* `checkout` will switch to the newly created branch. -* `-b` will create a new branch if the branch doesn't already exist - -This will create a new branch and move to it. Now, start hacking away and making any modifications you want. - -## Check git status - -After you've fixed the issue and tested it (Tests are critical! Never submit a change that hasn't been tested), you can keep track of your progress using this command: - -```shell -git status -``` - -This will show you which files are currently being modified and which branch you're working on. - -## Create a Pull Request - -A few considerations must be made before submitting a Pull Request. Your Pull Request will be merged more quickly if your branch is cleaned up. - -If any commits to the `upstream branch` have been made during the period you've been working on your changes, you will need to `rebase` your development branch so that merging it will be a fast-forward process without requiring any effort on conflict resolution. - -Fetch the upstream main branch and update your local repository by following these [steps on how to incorporate upstream changes](#how-to-incorporate-upstream-changes). - -Rebase your development branch if there were any new commits - -```shell -git checkout feature/newPage -git rebase -``` - -### Pull Request process - -A "Pull Request" (PR), as the name suggests, requests that another party pull your changes to their repository. In this case, you creating a PR means requesting that someone managing the Weaviate repo pull in changes from your fork. If successful, your changes will become a part of the upstream repository! - -Here are some general guidelines about how to submit a Pull Request: - -* If you're making visual changes, include a screenshot of the affected element before and after - -* Update the documentation if you change any user-facing functionality in Weaviate - -* Each Pull Request should implement one new feature or fix one bug. Submit multiple Pull Requests if you want to add or fix multiple items. - -* Do not commit changes to files that are irrelevant to your feature or bug fix - -* Write a good commit message. Check out [commit guidelines](./commit-guidelines.md) - -**Adding the files and committing:** - -First, make sure you are on your development branch. - -In git, files need to be 'staged' before being added to a commit. Prior to adding files to the staging area, always validate visually which files need to be staged. Check the tracked modifications in the git repository like so: - -```shell -git status -``` - -From here, you can add relevant files to the staging area. You can do so based on their filename: - -```shell -git add filename -``` - -You can also use `git add .` to stage all modified files in the current directory as well as subdirectories. But use this with care, as doing so might add irrelevant files, such as local configuration files for temporary files. - -To systematically ignore certain files or directories, you can create a [.gitignore](https://www.atlassian.com/git/tutorials/saving-changes/gitignore) file. - -You can run `git status` as many times as necessary to check what has been staged. You can also [unstage files](https://docs.gitlab.com/ee/topics/git/unstage.html) as necessary. - -* If everything is good to go, proceed with committing your changes. Try to add a concise and informative commit message - your future self and others will thank you for it. Read more about [commit guidelines here](./commit-guidelines.md). - -```shell -git commit -m "your commit message" -``` - -**Pushing the commit:** - -* To have your GitHub repo reflect changes made to your local repo, **push** to the remote repo: - -```shell -git push origin feature/newPage -``` - -If asked, enter your GitHub login credentials. When complete, all local commits will be on your GitHub repository. - -When all of your changes have been committed and pushed to GitHub, visit the page for your fork there, choose the development branch, and then press the `Compare & Pull Request` button. - -![create Pull Request](/img/contributor-guide/getting-started/pull_request.png) - -If you need to make any further commits to your Pull Request, simply check out your development branch and push the updates to GitHub. Your Pull Request will automatically keep track of and update the commits made to your development branch. - -* Complete the Pull Request by filling out our [Pull Request template](https://github.com/weaviate/weaviate/blob/master/.github/PULL_REQUEST_TEMPLATE.md) - -![Pull Request template](/img/contributor-guide/getting-started/pull_request_temp.png) - -* Once your changes are ready, make sure you [self review](#self-reviewing-pull-requests) your Pull Request to speed up the review process. - -## Self reviewing Pull Requests - -You should always review your own Pull Request first. - -For any changes you commit, make sure that you: - -* Confirm that the changes meet the objectives of the issue you created or are working on. - -* Compare your Pull Request's source changes to staging to ensure that the output matches the source and that everything is rendering as expected. This assists in detecting issues such as typos or content that isn't rendering due to versioning issues. - -* If there are failing checks in your PR, try to resolve them. If you get stuck, you can ask for help on the [community forum](https://forum.weaviate.io/) or [Slack](https://weaviate.io/slack). - -### Documentation-specific guidelines - -* Check for technical accuracy in the content. You can always [ask for help](https://weaviate.io/slack) if you get stuck. - -* Verify that the syntax of new or updated MDX or React statements is proper. - -## After submitting a Pull Request - -After you've created the Pull Request, there are two possibilities: - -* Your PR will be accepted, and your commit will be merged into the `` branch, congratulations! - -* Your PR will require further attention. This may happen due to: - * Irrelevant or breaking changes - * Reviewer wants something changed - -Working with git and GitHub can be intimidating at first, but it is a core part of how the open-source community works together to create such amazing tools. If you have any further questions, you can reach out to us also. - -We include some additional tips below. - -## Additional git / GitHub tips -### How to incorporate upstream changes - -A fork separates a repository from its upstream equivalent. So, you will need to pull upstream changes from time to time to keep your fork up to date with changes made upstream. - -To do this, first track the upstream repo by adding a remote upstream URL to the local repository. - -```shell -git remote add upstream https://github.com/weaviate/weaviate.git -``` - -* To check if your local copy properly references the upstream repository on GitHub, run the command below - -```shell -git remote -v -``` - -You should see: - -```shell -origin https://github.com/Your_Username/weaviate.git (fetch) -origin https://github.com/Your_Username/weaviate.git (push) -upstream https://github.com/weaviate/weaviate.git (fetch) -upstream https://github.com/weaviate/weaviate.git (push) -``` - -To bring in upstream changes to your fork, you need to fetch and pull the upstream repo's branches and commits. Here are two ways that you can do this: - -* [Using GitHub and git CLI](#fetch-upstream-with-github-and-git-cli) -* [Using git CLI](#fetch-upstream-with-git-cli) - -#### Fetch upstream with GitHub and git CLI - -* The first step is to incorporate any upstream changes to your forked repository. Head over to the forked GitHub repository, and under `Fetch Upstream`, click `Fetch and merge`. - -* The next step is to bring those changes to the local repository. If you have made any changes, make sure to commit them locally. Then check out the `main` branch like so: - -```shell -git checkout main -``` - -* Then pull the changes into local repository - -```shell -git pull origin main -``` - -This will update your local repository to reflect your remote, forked repository. - -#### Fetch upstream with git CLI - -Or you can just use the git CLI as below: - -* Check out the `main` branch first - -```shell -git checkout main -``` - -* Fetch the upstream changes - -```shell -git fetch upstream -``` - -* Then pull any changes from the upstream `main` branch into the current local branch (i.e. `main` - checked out earlier) - -```shell -git pull upstream main -``` - -* Last, push to your own remote repository (named `origin`) to keep the forked GitHub repo in sync - -```shell -git push origin main -``` - -One liner script for super users: - -```shell -git remote add upstream https://github.com/weaviate/weaviate.git || true && git fetch upstream && git checkout main && git pull upstream main && git push origin main -``` - -### View all branches including remote branches - -```shell -git branch -a -``` - -## Additional resources - -To learn more about git and GitHub, see: - -- [**GitHub Skills**](https://skills.github.com/) is a learning program provided by GitHub that teaches git and GitHub fundamentals. -- [**Pro Git Book**](https://git-scm.com/book/en/v2) is a comprehensive reference book on git. diff --git a/docs/contributor-guide/getting-started/improving-docs.md b/docs/contributor-guide/getting-started/improving-docs.md deleted file mode 100644 index 7700340a..00000000 --- a/docs/contributor-guide/getting-started/improving-docs.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Improving Documentation -description: Improving Documentation for Weaviate -sidebar_position: 4 -image: og/contributor-guide/getting-started.jpg -# tags: ['contributor-guide'] ---- -## Introduction - -Maintaining consistent, accurate and readable documentation is way to improve the user experience for everybody, including experienced users. - -The truth is that while we try our best, mistakes happen (we are not perfect! 😅). And if you found something difficult to understand, others may have too, which presents an opportunity for improvement. - -So if you spot any typos, errors, unclear explanations, missing references or anything that stands out, please let us know, and we can work on it together. - -## How Weaviate documentation is built - -Weaviate's documentation is built with a static site builder (Docusaurus) with data from our [GitHub repository](https://github.com/weaviate/docs). Before you get started, we suggest you set up a local development environment first. This will allow you to preview any changes on your computer as you work on it. - -For instructions on setting up the development environment, please take a look at this [README file](https://github.com/weaviate/docs/blob/main/README.md). - -Once your local environment is set up, you can make your proposed changes, preview them locally, and submit them for review. - - - -## MDX syntax - -You will notice MDX / React syntax throughout this site. Docusaurus has built-in support for MDX v1, which allows you to write JSX within your Markdown files and render them as React components. - -Read [this Docusaurus page](https://docusaurus.io/docs/markdown-features/react) for more information. - -## Infima styling - -This site uses Infima for styling. Read [this Docusaurus page](https://docusaurus.io/docs/styling-layout#styling-your-site-with-infima) for more information. - - - - - - -## Tests - -We've adopted a code sample structure that lets us both test and expose the samples without duplicating code. This is done using the `FilteredTextBlock` component, which loads arbitrary files and extract lines between a start marker and an end marker. You'll see statements like `import JSCode from '!!raw-loader!/_includes/code/howto/search.basics.ts';` in `.md` files, followed by - -```mdxjs - -``` - -To learn how to run tests, see the `README.md` file in `/tests/`. diff --git a/docs/contributor-guide/getting-started/index.md b/docs/contributor-guide/getting-started/index.md index 9ea1233e..6001068a 100644 --- a/docs/contributor-guide/getting-started/index.md +++ b/docs/contributor-guide/getting-started/index.md @@ -6,8 +6,6 @@ image: og/contributor-guide/getting-started.jpg # tags: ['contributor-guide'] --- -## Introduction - Welcome! Working with Weaviate, many of us in the team and the community are exposed to a suite of interesting technologies. They include not only vector databases, but also Docker, Kubernetes, GraphQL, REST and clients in various languages. This means that is a wide set of opportunities for you to learn about and contribute to! If you are not sure where, we suggest finding something that overlaps with your interests @@ -18,15 +16,13 @@ These are just some of the ways that you could apply your skills to the project: * [Suggesting Enhancements](./suggesting-enhancements.md) * [Reporting Bugs](./reporting-bugs.md) -* [Improving Documentation](./improving-docs.md) -* [Creating content/apps](./writing-blogs.md) ## Where can I contribute to? There are four major GitHub repositories of Weaviate, any of which you can contribute to. This includes: -* [Weaviate](https://github.com/weaviate/weaviate) - Weaviate's "core" codebase -* [Docs](https://github.com/weaviate/docs) - official Weaviate documentation +* [Weaviate Database](https://github.com/weaviate/weaviate) - Weaviate's "core" codebase +* [Weaviate Docs](https://github.com/weaviate/docs) - official Weaviate documentation * [Weaviate Examples](https://github.com/weaviate/weaviate-examples) - apps built using Weaviate * [Awesome Weaviate](https://github.com/weaviate/awesome-weaviate) - list of examples and tutorials on how to use Weaviate @@ -36,20 +32,3 @@ It is important that any contributions such as suggestions or bug reports be mad You can also contribute by working on existing issues. Check the issues pages in Weaviate's GitHub repositories like the [Weaviate Database repository](https://github.com/weaviate/weaviate/issues). Consider starting with issues tagged '[good first issues](https://github.com/weaviate/weaviate/labels/good-first-issue)'. -## Background reading - -Navigating a new project can be difficult, and it takes time to become acquainted with the codebase. If you haven't yet, we suggest going through the [Weaviate getting started guide](/weaviate/quickstart/index.md). - -Here are additional resources that will help you familiarize with Weaviate and its applications: - -* [Weaviate Blog](https://weaviate.io/blog) – a series of blog around Weaviate and the overall vector search space. -* [Weaviate Newsletter](https://newsletter.weaviate.io) – bi-weekly newsletter with updates on the latest and greatest announcements. -* [Awesome Weaviate](https://github.com/weaviate/awesome-weaviate) – a list of curated examples and tutorials on how to use Weaviate. -* [Weaviate Examples](https://github.com/weaviate/weaviate-examples) – a repository of various example projects created by the community. Each example shows a different Weaviate use case. You can add your own examples too! -* [Weaviate's YouTube Channel](https://www.youtube.com/c/SeMI-and-Weaviate/featured) – podcasts and live demos showcasing Weaviate, and providing insight into the vector search space in general. - -## Learn about git / GitHub - -Like many other open-source projects, the Weaviate community uses the git/GitHub ecosystem for collaborative development. If you are not familiar with git and GitHub basics, we have a guide on [how to contribute to Weaviate with git and GitHub](./git-and-github.md). - -Regardless of your choice, we are very excited to have you be a part of our community. Welcome 🙂. diff --git a/docs/contributor-guide/getting-started/reporting-bugs.md b/docs/contributor-guide/getting-started/reporting-bugs.md index bbac8df6..25093a31 100644 --- a/docs/contributor-guide/getting-started/reporting-bugs.md +++ b/docs/contributor-guide/getting-started/reporting-bugs.md @@ -1,5 +1,5 @@ --- -title: Reporting Bugs +title: Reporting bugs sidebar_position: 3 image: og/contributor-guide/getting-started.jpg # tags: ['contributor-guide'] @@ -9,19 +9,21 @@ We include brief guidelines below for submitting bug reports. These guidelines a ## How to write bug reports -Bug reports are tracked as GitHub issues, such as these in [Weaviate Database](https://github.com/weaviate/weaviate/issues). +Bug reports are tracked as GitHub issues, such as these in [weaviate/weaviate](https://github.com/weaviate/weaviate/issues). Once you've determined which repository your bug is related to, check first for a duplicate WIP (work in progress) issue. If not, open an issue in that repository with **a complete, specific and accurate description**. We recommend using this [template](https://github.com/weaviate/docs/blob/main/.github/ISSUE_TEMPLATE/report_bug.yml). -* **Use a clear and descriptive title** for the issue. -* **Describe the exact steps** needed to reproduce the problem with as much detail as possible. For example, include any custom Weaviate configurations, modules used or shell commands. -* **Give specific examples** to show the bug. This could be links or code snippets. For snippets, [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines) are better than images or animated GIFs. -* Explain what **you expected to see instead** and why. -* (If relevant) **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. -* If the problem was not caused by a specific action, describe what you were doing before the problem occurred and any additional information which may help to reproduce or identify the problem. +- **Use a clear and descriptive title** for the issue. +- **Describe the exact steps** needed to reproduce the problem with as much detail as possible. For example, include any custom Weaviate configurations, modules used or shell commands. +- **Give specific examples** to show the bug. This could be links or code snippets. For snippets, [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines) are better than images or animated GIFs. +- Explain what **you expected to see instead** and why. +- (If relevant) **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. +- If the problem was not caused by a specific action, describe what you were doing before the problem occurred and any additional information which may help to reproduce or identify the problem. -## Read more +## Questions and feedback -We also encourage you to check out this more detailed guide on [Writing great Bug Reports](/weaviate/more-resources/write-great-bug-reports.md) from our team. +import DocsFeedback from "/\_includes/docs-feedback.mdx"; + + diff --git a/docs/contributor-guide/getting-started/suggesting-enhancements.md b/docs/contributor-guide/getting-started/suggesting-enhancements.md index d4533fb4..e4510be9 100644 --- a/docs/contributor-guide/getting-started/suggesting-enhancements.md +++ b/docs/contributor-guide/getting-started/suggesting-enhancements.md @@ -1,27 +1,49 @@ --- -title: Suggesting Enhancements +title: Feature requests and enhancements +sidebar_label: Feature requests sidebar_position: 2 image: og/contributor-guide/getting-started.jpg # tags: ['contributor-guide'] --- + We love to hear your ideas. Here are some guidelines for suggesting enhancements. They are designed to make it easier for the maintainers and the community to understand your proposal, which will make it more likely to be adopted. +## Requesting new features + +Have an idea for improving Weaviate? We'd love to hear it! You can submit feature requests through either channel: + +- **[GitHub Issues](https://github.com/weaviate/weaviate/labels/feature%20request)** - Create a feature request issue +- **[Community Forum](https://forum.weaviate.io/tag/feature-request)** - Start a discussion with the `feature-request` tag + +When submitting a feature request, you should: + +- **Check for duplicates** - Search existing requests to avoid duplicates +- **Be clear and specific** - Use a descriptive title and explain what the feature should do +- **Explain the value** - Why would this be useful to Weaviate users? +- **Provide examples** - Include code snippets, use cases, or mockups if helpful + ## How to suggest enhancements -Suggestions are tracked as GitHub issues, such as these in [Weaviate Database](https://github.com/weaviate/weaviate/issues). Check first for a duplicate WIP (work in progress) issue. If not, create an issue in the relevant GitHub repository with the following: +Suggestions are tracked as issues in GitHub repositories, such as the [Weaviate repository](https://github.com/weaviate/weaviate/issues). Check first for a duplicate WIP (work in progress) issue. If not, create an issue in the relevant GitHub repository with the following: -* **Use a clear and descriptive title**. -* **A specific and accurate description** of the suggested enhancement; include steps if necessary. -* **Specific examples(s)**. If possible, include code snippets in Markdown format. -* (If relevant) **Describe the current behavior** and then **explain how it would be altered**. -* (If relevant) **Include images, animated GIFs, or video links** in support. -* **Explain why this change would be useful** to Weaviate users. -* Specify which **version of Weaviate** you're using. Check the version in your `docker-compose.yml` file. +- **Use a clear and descriptive title**. +- **A specific and accurate description** of the suggested enhancement; include steps if necessary. +- **Specific examples(s)**. If possible, include code snippets in Markdown format. +- (If relevant) **Describe the current behavior** and then **explain how it would be altered**. +- (If relevant) **Include images, animated GIFs, or video links** in support. +- **Explain why this change would be useful** to Weaviate users. +- Specify which **version of Weaviate** you're using. ## Working on your own ideas You are welcome to implement your own ideas and contribute code to Weaviate! We love to hear your ideas. Feel free to reach out to us and the wider community on the [forum](https://forum.weaviate.io) to discuss them before you get started. If you want to implement your ideas, or do some work on the Weaviate code base, follow these [instructions](../weaviate-core/setup.md) to create a local development environment. + +## Questions and feedback + +import DocsFeedback from "/\_includes/docs-feedback.mdx"; + + diff --git a/docs/contributor-guide/getting-started/writing-blogs.md b/docs/contributor-guide/getting-started/writing-blogs.md deleted file mode 100644 index 233ba87c..00000000 --- a/docs/contributor-guide/getting-started/writing-blogs.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Creating Content / Apps -sidebar_position: 5 -image: og/contributor-guide/getting-started.jpg -# tags: ['contributor-guide'] ---- -The Weaviate community produces a lot of great content including blog posts, tutorials, and demo applications. To help these reach the broader community, we maintain a curated list of these in our [Awesome Weaviate](https://github.com/weaviate/awesome-weaviate) repository. - -If you would like to share your own work, we would love to hear from you. We can help it reach the wider Weaviate community, who will in turn benefit from your work. - -Here are some ideas and tips on how: - -## Write a blog post or tutorial - -You could contribute by writing a blog post, or tutorial relating to Weaviate. - -It could be about anything from your Weaviate journey, concepts you've learnt and used with Weaviate like vector databases, or guides on how to integrate Weaviate with something. - -It can be hosted anywhere. It could be at a well-known platform such as Medium, Dev.to, or HashNode, or somewhere smaller like your own blog. - -We ask of your article to: - -* Be freely accessible -* Use the `weaviate` tag (where applicable) -* Use code blocks, rather than screenshots of code (for usability) - -## Develop a demo app - - -You could also contribute by creating a demo application that uses Weaviate under the hood. It can be a web app, mobile app or demos showing certain [integrations](/weaviate/more-resources/example-use-cases.md). - -We ask for the app to: - -* Be unique -* Include a descriptive README.md file if possible -* Disclose the Weaviate [module(s)](/weaviate/modules/index.md) used - -## Create a PR when ready - -When you are ready to share your work, create a pull request in [Awesome Weaviate](https://github.com/weaviate/awesome-weaviate) repository. - -## Resources - -* [Tutorials by Weaviate](/weaviate/tutorials/index.mdx) -* [Example Datasets](/weaviate/more-resources/example-datasets.md) -* [Podcasts by Weaviate](https://weaviate.io/podcast) -* [Developer Style Guide (FreeCodeCamp)](https://www.freecodecamp.org/news/developer-news-style-guide/) - -If you need help, reach out to us on the [Community Forum](https://forum.weaviate.io) or [Slack](https://weaviate.io/slack). diff --git a/docs/contributor-guide/index.md b/docs/contributor-guide/index.md deleted file mode 100644 index 7d57f0f1..00000000 --- a/docs/contributor-guide/index.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Open-source at Weaviate -sidebar_position: 0 -image: og/contributor-guide/welcome.jpg -# tags: ['index', 'contributor-guide'] ---- -![Contributor Guide](/img/contributor-guide/Weaviate.jpg) - -🎉 First off, thank you for taking the time to contribute! 🎉 - -We are delighted to have you here. We are thrilled that you want to contribute to Weaviate Database, as together we can make Weaviate even better. We strive to build an engaging community and we encourage you to participate, share your ideas and make friends. - -## Weaviate on GitHub - -If you're using Weaviate or if you like the project, please ⭐ this repository to show your support! - -## Contributor Guide Structure - -We recommend reading through the [Contributors' getting started guide](./getting-started/index.md) first. That includes suggestions on different ways to contribute, as well as how you can make those contributions. - -This guide also includes the following sections on specific areas. You can think of these as more technical, reference guides on each area for contributors. -- [Weaviate Database](./weaviate-core/index.md) -- [Weaviate Modules](./weaviate-modules/index.md) -- [Contextionary](./contextionary/index.md) -- [Weaviate Clients](./weaviate-clients/index.md) - -## Join the Weaviate Community - -A lot of community chat happens on the [Weaviate Community Slack](https://weaviate.io/slack), with longer-form discussions taking place on the [forum](https://forum.weaviate.io) - -Many members of our community help us by giving feedback, asking questions, or proposing ideas. To get involved in our community, please make sure to familiarize yourself with the project's [Code of Conduct](https://weaviate.io/service/code-of-conduct). - -Please set your forum or Slack workspace display name to your name. This will make it easier to connect with other community members. Then reach out to members of the community, introduce yourself, and share your ideas/questions. Tell us about your areas of interest and what technologies you are using to build your projects. The more we know about you, the better we will be able to match project requirements to your interests and abilities. - -If at any time you face any difficulties, don't hesitate to reach out in the `#general` channel on our Slack for quick help, or in the [General category of the forum](https://forum.weaviate.io/c/general/4) for more complex issues. Our team and the community will help you solve your problem. - -## License - -Please refer to each individual repository for relevant licensing information. - -import CustomScriptLoader from '/src/components/scriptSwitch'; - - \ No newline at end of file diff --git a/docs/contributor-guide/index.mdx b/docs/contributor-guide/index.mdx new file mode 100644 index 00000000..ebece13d --- /dev/null +++ b/docs/contributor-guide/index.mdx @@ -0,0 +1,104 @@ +--- +title: Open-source at Weaviate +image: og/contributor-guide/welcome.jpg +# tags: ['index', 'contributor-guide'] +--- + +First off, thank you for taking the time to contribute! + +We are delighted to have you here. We are thrilled that you want to contribute to Weaviate Database, as together we can make Weaviate even better. We strive to build an engaging community and we encourage you to participate, share your ideas and make friends. + +If you're using Weaviate or if you like the project, please give a star to the **[Weaviate repository](https://github.com/weaviate/weaviate)** to show your support! + +## Getting started + +import CardsSection from "/src/components/CardsSection"; +export const gettingStartedData = [ + { + title: "Feature requests", + description: + "Have an idea for a new feature or enhancement? Share your suggestions to help shape Weaviate's future development.", + link: "/contributor-guide/getting-started/suggesting-enhancements", + icon: "fas fa-lightbulb", + }, + { + title: "Report bugs", + description: + "Found something broken? Help us improve Weaviate by reporting bugs with clear reproduction steps and detailed information.", + link: "/contributor-guide/getting-started/reporting-bugs", + icon: "fas fa-bug", + }, +]; + + + +## Contributor guides + +Choose a specific guide based on the project you are working on: + +export const contributionAreasData = [ + { + title: "Weaviate Database", + description: + "The main database engine written in Go. Contains relevant information for anyone working with the Weaviate Database source code.", + link: "/contributor-guide/weaviate-core", + icon: "fas fa-database", + }, + { + title: "Weaviate Docs", + description: + "For technical writers and developers who are contributing to the Weaviate Documentation.", + link: "/contributor-guide/weaviate-docs", + icon: "fas fa-book", + }, + { + title: "Client Libraries", + description: + "Guide for language-specific developers who want to improve SDK design and developer experience.", + link: "/contributor-guide/weaviate-clients", + icon: "fas fa-code", + }, + { + title: "Modules", + description: + "Extend Weaviate with new capabilities. Perfect for AI/ML practitioners and integration specialists working with Python and machine learning APIs.", + link: "/contributor-guide/weaviate-modules", + icon: "fas fa-puzzle-piece", + }, +]; + + + +## Join the Weaviate Community + +A lot of community chat happens on the [Weaviate Community Slack](https://weaviate.io/slack), with longer-form discussions taking place on the [forum](https://forum.weaviate.io) + +Many members of our community help us by giving feedback, asking questions, or proposing ideas. To get involved in our community, please make sure to familiarize yourself with the project's [Code of Conduct](https://weaviate.io/service/code-of-conduct). + +Please set your forum or Slack workspace display name to your name. This will make it easier to connect with other community members. Then reach out to members of the community, introduce yourself, and share your ideas/questions. Tell us about your areas of interest and what technologies you are using to build your projects. The more we know about you, the better we will be able to match project requirements to your interests and abilities. + +If at any time you face any difficulties, don't hesitate to reach out in the `#general` channel on our Slack for quick help, or in the [General category of the forum](https://forum.weaviate.io/c/general/4) for more complex issues. Our team and the community will help you solve your problem. + +## License + +Please refer to each individual repository for relevant licensing information. + +- **Weaviate Database license**: [BSD 3-Clause "New" or "Revised" License](https://github.com/weaviate/weaviate/blob/main/LICENSE) + +## Further resources + +Navigating a new project can be difficult, and it takes time to become acquainted with the codebase. If you haven't yet, we suggest going through the [Weaviate Quickstart guide](/weaviate/quickstart/index.md). + +Here are additional resources that will help you familiarize with Weaviate and its applications: + +- [Weaviate Blog](https://weaviate.io/blog) – a series of blog around Weaviate and the overall vector search space. +- [Weaviate Newsletter](https://newsletter.weaviate.io) – bi-weekly newsletter with updates on the latest and greatest announcements. +- [Awesome Weaviate](https://github.com/weaviate/awesome-weaviate) – a list of curated examples and tutorials on how to use Weaviate. +- [Weaviate Examples](https://github.com/weaviate/weaviate-examples) – a repository of various example projects created by the community. Each example shows a different Weaviate use case. You can add your own examples too! +- [Weaviate's YouTube Channel](https://www.youtube.com/c/SeMI-and-Weaviate/featured) – podcasts and live demos showcasing Weaviate, and providing insight into the vector search space in general. + +## Questions and feedback + +import DocsFeedback from "/_includes/docs-feedback.mdx"; + + diff --git a/docs/contributor-guide/profile001.png b/docs/contributor-guide/profile001.png deleted file mode 100644 index 319b5534..00000000 Binary files a/docs/contributor-guide/profile001.png and /dev/null differ diff --git a/docs/contributor-guide/weaviate-clients/_category_.json b/docs/contributor-guide/weaviate-clients/_category_.json deleted file mode 100644 index 9af44628..00000000 --- a/docs/contributor-guide/weaviate-clients/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Weaviate Clients", - "position": 6 -} diff --git a/docs/contributor-guide/weaviate-clients/index.md b/docs/contributor-guide/weaviate-clients/index.md index c11450eb..d72ee9d9 100644 --- a/docs/contributor-guide/weaviate-clients/index.md +++ b/docs/contributor-guide/weaviate-clients/index.md @@ -1,30 +1,28 @@ --- title: Weaviate Clients -sidebar_position: 0 image: og/contributor-guide/weaviate-clients.jpg # tags: ['contributor-guide', 'clients'] --- -# Contributor guidelines - There are currently four clients developed for Weaviate's APIs: -* [Python](/weaviate/client-libraries/python/index.mdx) -* [Go](/weaviate/client-libraries/go.md) -* [TypeScript/JavaScript](../../weaviate/client-libraries/typescript/index.mdx) -* [Java](/weaviate/client-libraries/java.md) + +- **[Python](/weaviate/client-libraries/python/index.mdx)** +- **[TypeScript/JavaScript](../../weaviate/client-libraries/typescript/index.mdx)** +- **[Java](/weaviate/client-libraries/java.md)** +- **[Go](/weaviate/client-libraries/go.md)** These clients, and all future clients are and will be developed according to the following guidelines: -1. Every client *must* reflect all features of the [RESTful API one-to-one](/weaviate/api/rest). -2. Every client *must* reflect all functions of [GraphQL API](/weaviate/api/index.mdx) (1-1 where possible). -3. Clients *can* have client-specific, extra or unique features: +1. Every client _must_ reflect all features of the [RESTful API one-to-one](/weaviate/api/rest). +2. Every client _must_ reflect all functions of [GraphQL API](/weaviate/api/index.mdx) (1-1 where possible). +3. Clients _can_ have client-specific, extra or unique features: 1. These features on top of the 1-1 RESTful and GraphQL functionalities must be defined through a user story, which will also be reflected in the documentation. 2. These features can be solved in a client's native way (follow the current design of the client for consistency) 3. Preferably the functionalities are consistent across clients. 4. Keep the design (nomenclature and builder structures) as consistent as possible, with the nomenclature of the RESTful and GraphQL API functions as base, then adopting names from similar functions in a client in another language. 5. To be considered complete, clients must, at a minimum, include journey tests. Please refer to the 'Testing' section below for more details." -# Design philosophy and API patterns +## Design philosophy and API patterns As a rule of thumb it is more important that a client feels native to developers used to a specific language than it is to have all clients exactly @@ -43,7 +41,7 @@ suited for a builder pattern. Casing in object, property and method names should follow best-practicies for the respective language. -# Testing +## Testing Test coverage is very important for clients to make it possible to easily test the client against various Weaviate versions. As a client is an integration @@ -67,15 +65,15 @@ tests of the JavaScript client or Go client ([Example](https://github.com/weaviate/weaviate-go-client/tree/master/test)). -# How to get started +## How to get started We recommend that you first identify which existing client uses a language most similar to the one you've picked. For example, criteria could include: -* Is the language dynamically or statically typed? -* Is the language compiled or interpreted? -* How are optional arguments typically handled? -* How verbose are patterns in the language? +- Is the language dynamically or statically typed? +- Is the language compiled or interpreted? +- How are optional arguments typically handled? +- How verbose are patterns in the language? Then you can take a look at an existing client which matches your language the closest and get inspried. @@ -93,3 +91,9 @@ correctly. Eventually, as you have ported all tests and implemented all features to make them pass, you have the guarantee that your client is feature-complete and won't break on future updates. + +## Questions and feedback + +import DocsFeedback from '/\_includes/docs-feedback.mdx'; + + diff --git a/docs/contributor-guide/weaviate-core/_category_.json b/docs/contributor-guide/weaviate-core/_category_.json deleted file mode 100644 index 78600481..00000000 --- a/docs/contributor-guide/weaviate-core/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Weaviate Database", - "position": 3 -} diff --git a/docs/contributor-guide/weaviate-core/cicd.md b/docs/contributor-guide/weaviate-core/cicd.md index 39df028b..9de45f9f 100644 --- a/docs/contributor-guide/weaviate-core/cicd.md +++ b/docs/contributor-guide/weaviate-core/cicd.md @@ -1,6 +1,5 @@ --- -title: CICD Philosophy -sidebar_position: 2 +title: CICD philosophy image: og/contributor-guide/weaviate-core.jpg # tags: ['contributor-guide'] --- @@ -40,32 +39,14 @@ In practice this means: prepared to merge your contribution even if it's not fully complete yet. We can always hide unfinished features from users using feature toggles, etc. -## Semantic Versioning +## Semantic versioning We generally aim to avoid breaking changes. Having to update a major version frequently is annoying - but it is even more annoying for the user to have to try to fix a bug themselves. Weaviate uses semantic versioning to indicate to users that an upgrade path is -safe. Having said that, pre-`v1.0.0`, there were some special situations: - -### Versions 0.x.y - -Since we have no good way of indicating breaking changes without raising the -major version, we have come up with the following scheme while we are below -version `v1.0.0`: - -* Both patches and new features are indicated in the patch version. E.g. - `0.22.18` might contain new (non-breaking) features as well as fixes over - `0.22.17`. -* Breaking changes (which should happen very rarely) increase the minor - version. E.g. `0.23.0` will contain breaking changes over `0.22.x`. This - workaround will no longer be required once version `v1.0.0` is published and - proper semantic versioning can be done. - -### Versions 1.x.y and larger - -Versions v1.0.0 and onwards use Semantic Versioning as it was intended. +safe. ## Deprecations @@ -115,11 +96,9 @@ adhere to the following steps: changes, and link to the respective issues. Check prior releases for inspiration. -## More Resources - -import ContributorGuideMoreResources from '/_includes/more-resources-contributor-guide.md'; +## Further resources - +- [Weaviate GitHub repository](https://github.com/weaviate/weaviate/) ## Questions and feedback diff --git a/docs/contributor-guide/weaviate-core/index.md b/docs/contributor-guide/weaviate-core/index.md index 22360f2a..cdacd3c4 100644 --- a/docs/contributor-guide/weaviate-core/index.md +++ b/docs/contributor-guide/weaviate-core/index.md @@ -1,13 +1,56 @@ --- title: Weaviate Database -sidebar_position: 0 image: og/contributor-guide/weaviate-core.jpg # tags: ['build, run, test'] --- -- [Code structure and style](./structure.md) -- [CICD philosophy](./cicd.md) -- [Test philosophy of Weaviate](./tests.md) -- [Weaviate development setup](./setup.md) -- [Parsing Objects & Resolving References](./parsing-cross-refs.md) -- [Adding runtime configurations](./support-new-runtime-configs.md) +Here you can find guides on how to work with the Weaviate Database [source code](https://github.com/weaviate/weaviate). + +import CardsSection from "/src/components/CardsSection"; + +export const weaviateCoreGuidesData = [ +{ +id: "structure", +title: "Code structure and style", +description: "Learn Weaviate's codebase organization, coding standards, and style guidelines for consistent development.", +link: "/contributor-guide/weaviate-core/structure", +icon: "fas fa-code", +}, +{ +id: "cicd", +title: "CI/CD philosophy", +description: "Understand our continuous integration and deployment approach, including automated testing and release processes.", +link: "/contributor-guide/weaviate-core/cicd", +icon: "fas fa-sync-alt", +}, +{ +id: "tests", +title: "Tests", +description: "Explore Weaviate's testing strategy, including unit tests, integration tests, and quality assurance practices.", +link: "/contributor-guide/weaviate-core/tests", +icon: "fas fa-vial", +}, +{ +id: "setup", +title: "Development setup", +description: "Set up your local Weaviate development environment with all necessary tools and dependencies.", +link: "/contributor-guide/weaviate-core/setup", +icon: "fas fa-cogs", +}, +{ +id: "parsing", +title: "Parsing objects & resolving references", +description: "Deep dive into how Weaviate parses objects and resolves cross-references internally.", +link: "/contributor-guide/weaviate-core/parsing-cross-refs", +icon: "fas fa-project-diagram", +}, +{ +id: "runtime-config", +title: "Runtime configurations", +description: "Learn how to add new runtime configuration options to Weaviate's configuration system.", +link: "/contributor-guide/weaviate-core/support-new-runtime-configs", +icon: "fas fa-sliders-h", +}, +]; + + diff --git a/docs/contributor-guide/weaviate-core/parsing-cross-refs.md b/docs/contributor-guide/weaviate-core/parsing-cross-refs.md index 833e4957..44c1f5b7 100644 --- a/docs/contributor-guide/weaviate-core/parsing-cross-refs.md +++ b/docs/contributor-guide/weaviate-core/parsing-cross-refs.md @@ -1,7 +1,6 @@ --- -title: Parsing Objects & Resolving References +title: Parsing objects & resolving references description: Guide to parsing cross-references in Weaviate Database for data linking. -sidebar_position: 5 image: og/contributor-guide/weaviate-core.jpg # tags: ['contributor-guide'] --- @@ -64,11 +63,9 @@ The cached resolver is a helper struct with a two-step process: * [The reference Resolver](https://github.com/weaviate/weaviate/blob/master/adapters/repos/db/refcache/resolver.go) and its [unit tests](https://github.com/weaviate/weaviate/blob/master/adapters/repos/db/refcache/resolver_test.go) * Integration tests for [nested refs](https://github.com/weaviate/weaviate/blob/master/adapters/repos/db/crud_references_integration_test.go) and [refs of different types](https://github.com/weaviate/weaviate/blob/master/adapters/repos/db/crud_references_multiple_types_integration_test.go) -## More Resources +## Further resources -import ContributorGuideMoreResources from '/_includes/more-resources-contributor-guide.md'; - - +- [Weaviate GitHub repository](https://github.com/weaviate/weaviate/) ## Questions and feedback diff --git a/docs/contributor-guide/weaviate-core/setup.md b/docs/contributor-guide/weaviate-core/setup.md index 0f5fee73..30b3961b 100644 --- a/docs/contributor-guide/weaviate-core/setup.md +++ b/docs/contributor-guide/weaviate-core/setup.md @@ -1,6 +1,5 @@ --- -title: Weaviate development setup -sidebar_position: 4 +title: Development setup image: og/contributor-guide/weaviate-core.jpg # tags: ['contributor-guide'] --- @@ -74,11 +73,9 @@ The above commands are subject to change as we add more modules and require spec To make queries from a web interface, use the [WCD console](https://console.weaviate.cloud) to connect to `localhost:8080`. -## More Resources +## Further resources -import ContributorGuideMoreResources from '/_includes/more-resources-contributor-guide.md'; - - +- [Weaviate GitHub repository](https://github.com/weaviate/weaviate/) ## Questions and feedback diff --git a/docs/contributor-guide/weaviate-core/structure.md b/docs/contributor-guide/weaviate-core/structure.md index fe6801cd..24d61214 100644 --- a/docs/contributor-guide/weaviate-core/structure.md +++ b/docs/contributor-guide/weaviate-core/structure.md @@ -1,6 +1,5 @@ --- -title: Code structure and Style -sidebar_position: 1 +title: Code structure and style image: og/contributor-guide/weaviate-core.jpg # tags: ['contributor-guide'] --- @@ -85,11 +84,9 @@ The following guidelines help us write clean and maintainable code: not be 100% obvious. It's better to have a few 100-line comments, than to have 100s of 1-line comments which don't add any value. -## More Resources +## Further resources -import ContributorGuideMoreResources from '/_includes/more-resources-contributor-guide.md'; - - +- [Weaviate GitHub repository](https://github.com/weaviate/weaviate/) ## Questions and feedback diff --git a/docs/contributor-guide/weaviate-core/support-new-runtime-configs.md b/docs/contributor-guide/weaviate-core/support-new-runtime-configs.md index 145c35a0..f6270e6e 100644 --- a/docs/contributor-guide/weaviate-core/support-new-runtime-configs.md +++ b/docs/contributor-guide/weaviate-core/support-new-runtime-configs.md @@ -1,6 +1,5 @@ --- -title: Adding runtime configurations -sidebar_position: 6 +title: Runtime configurations image: og/contributor-guide/weaviate-core.jpg # tags: ['contributor-guide'] --- @@ -87,3 +86,14 @@ To access the current value of the config, use `config.MaxLimit.Get()` instead o :::info When `RUNTIME_OVERRIDES_ENABLED=false`, your config still behaves as a static config and uses the default value (`12` in this example) provided via `NewDynamicValue(12)`. ::: + +## Further resources + +- [Configuration: Runtime configuration management](/deploy/configuration/env-vars/runtime-config.md) +- [Weaviate GitHub repository](https://github.com/weaviate/weaviate/) + +## Questions and feedback + +import DocsFeedback from '/_includes/docs-feedback.mdx'; + + diff --git a/docs/contributor-guide/weaviate-core/tests.md b/docs/contributor-guide/weaviate-core/tests.md index 81dc7097..2c9bb0c5 100644 --- a/docs/contributor-guide/weaviate-core/tests.md +++ b/docs/contributor-guide/weaviate-core/tests.md @@ -5,7 +5,7 @@ image: og/contributor-guide/weaviate-core.jpg # tags: ['contributor-guide'] --- -## Philosophy +## Testing philosophy ### Test Pyramid @@ -45,8 +45,8 @@ Backing services are always ephemeral and will be created solely for the tests. These tests have two functions: -1) Identify regressions automatically before they are merged. -2) Enable performance tracking over time. +1. Identify regressions automatically before they are merged. +2. Enable performance tracking over time. They are currently very limited but will be extended over time. @@ -86,11 +86,12 @@ go test ./... #### Adding new unit tests -* Add unit tests in the same folder as the code they are testing -* Aim to write "black box" unit tests that test the public ("exported") methods of the class under test without knowing too much about the internals. -* Do not use any build tags. +- Add unit tests in the same folder as the code they are testing +- Aim to write "black box" unit tests that test the public ("exported") methods of the class under test without knowing too much about the internals. +- Do not use any build tags. ### Integration tests + As outline in the Philosophy, integration tests require backing services to be run. We have a convenience script available which starts all required services in `Docker Compose` and runs the tests against it: ```sh @@ -99,9 +100,9 @@ test/integration/run.sh #### Adding new integration tests -* Use the `integrationTest` build tag on your test, so it is ignored during unit test runs. -* Make sure the test prepares for and cleans up after itself, so tests can be run in succession. -* If your test requires a lot of time to execute, consider marking it as a slow test and making it optional. (see below). +- Use the `integrationTest` build tag on your test, so it is ignored during unit test runs. +- Make sure the test prepares for and cleans up after itself, so tests can be run in succession. +- If your test requires a lot of time to execute, consider marking it as a slow test and making it optional. (see below). #### Slow integration tests @@ -120,6 +121,7 @@ Note that while slow tests are optional on the integration test runner script, t To mark an integration test as "slow" simply use the `integrationTestSlow` build tag, instead of the `integrationTest` tag. ### Journey tests + As outline in the Philosophy, journey tests require the application to be compiled as well as all backing services to be running. We have a convenience script available which starts all required services in `Docker Compose` and runs the tests against it. The script is part of the overall pipeline script, but you can configure it to run only the journey tests like so: @@ -129,6 +131,7 @@ test/run.sh --acceptance-only ``` #### Add a new journey test + Journey tests don't use any specific build tags, however, they are all isolated in a specific folder. This folder is ignored during integration or unit test runs. To add a new test, pick the most appropriate sub-folder (or add a new one) in `test/acceptance`. @@ -158,6 +161,7 @@ Prefer the use of [stretchr/testify](https://github.com/stretchr/testify) to mak If there are cases which cannot be solved using `testify`, write a manual assertion. ### Catastrophic Failure of tests + Use the `assert` package if a failure of this tests is not catastrophic and use the `require` package if a test should not execute beyond a failure. A typical scenario for this is checking for an error when we know that the other return value would be nil otherwise. For example: @@ -172,14 +176,12 @@ If we didn't use `require` on the error, the test would continue executing. Ther By using `require.Nil` we can abort this test early, if an unexpected error was returned. -## More Resources - -import ContributorGuideMoreResources from '/_includes/more-resources-contributor-guide.md'; +## Further resources - +- [Weaviate GitHub repository](https://github.com/weaviate/weaviate/) ## Questions and feedback -import DocsFeedback from '/_includes/docs-feedback.mdx'; +import DocsFeedback from '/\_includes/docs-feedback.mdx'; - \ No newline at end of file + diff --git a/docs/contributor-guide/weaviate-docs/development.mdx b/docs/contributor-guide/weaviate-docs/development.mdx new file mode 100644 index 00000000..004b8239 --- /dev/null +++ b/docs/contributor-guide/weaviate-docs/development.mdx @@ -0,0 +1,349 @@ +--- +title: Setup and editing +description: Complete guide for editing and building Weaviate documentation +image: og/contributor-guide/getting-started.jpg +# tags: ['contributor-guide'] +--- + +This guide covers the essential workflows and components for editing Weaviate's documentation. Whether you're adding new content, updating existing pages, or working with interactive components, this reference will help you work effectively with our Docusaurus-based documentation system. + +Following these guidelines ensures consistency across the documentation and maintains the quality of the user experience. + +## Building the documentation locally + +**Start development server** for live editing with hot reload: + +```bash +yarn start +``` + +This launches a local development server, typically at `http://localhost:3000`, where you can see your changes instantly as you edit files. + +**Build the documentation** for production: + +```bash +yarn build +``` + +This creates an optimized production build in the `build/` directory and validates all links, references, and configurations. Always run this before submitting pull requests to catch any issues. + +**Serve the built documentation** locally: + +```bash +yarn serve +``` + +This serves the production build locally, useful for testing the built version before deployment. The site will be available at `http://localhost:3000`. + +### Build Validation + +The build process performs several important validations: + +- **Link checking**: Verifies all internal links point to existing pages +- **Reference validation**: Ensures all imports and components are valid +- **Markdown processing**: Converts MDX to HTML and catches syntax errors +- **Plugin execution**: Runs plugins like llms.txt generation + +Always fix any build errors before submitting changes, as broken builds will prevent deployment. + +## Linking within the docs + +### Relative link paths + +**Use relative paths** when linking within the same documentation section: + +```markdown + + +[Quickstart guide](./quickstart/index.md) + + + +[Weaviate Agents](../index.md) +``` + +### Absolute link paths + +**Use absolute paths** for cross-section linking: + +```markdown + + +[Weaviate Agents](/agents/index.md) + + + +[Weaviate Database](/weaviate/index.md) +``` + +### Absolute URLs + +**Use absolute URLs** for reusable components: + +```markdown + + +[Weaviate Agents](/agents/qeuery) +``` + +This convention ensures links work correctly regardless of where the component is imported. + +### `Link` component + +For internal links in JSX/MDX content, use Docusaurus's `Link` component instead of HTML `` tags to enable link checking: + +```jsx +import Link from '@docusaurus/Link'; + +// Good - enables link validation +Get started with Weaviate + +// Avoid - bypasses link checking +Get started with Weaviate +``` + +The `Link` component performs validation during build time and will report broken internal links as build errors. + +### `SkipLink` for component + +When linking to scalar OpenAPI reference documentation that may not be available during build, use SkipLink to skip validation: + +```jsx +import SkipLink from "/src/components/SkipValidationLink"; + +References: REST API: Backups +``` + +This prevents build failures while still providing the correct link to users. Use this sparingly and only for external references that are known to be valid but unavailable during build. + +## Code snippets + +### `FilteredTextBlock` component + +`FilteredTextBlock` allows you to include specific sections of code files, keeping examples up-to-date with tested code. Use Tabs to provide code examples in multiple languages. + +```jsx +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock"; +import PyCode from "!!raw-loader!/_includes/code/howto/manage-data.aliases.py"; +import TSCode from "!!raw-loader!/_includes/code/howto/manage-data.aliases.ts"; +import GoCode from "!!raw-loader!/_includes/code/howto/go/docs/manage-data.aliases_test.go"; +import JavaCode from "!!raw-loader!/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java"; + + + + + + + + + + + + + + +; +``` + +### Marker conventions + +Use consistent marker patterns in your source code files: + +- **Python**: + - `# START SectionName` + - `# END SectionName` +- **JavaScript/TypeScript**: + - `// START SectionName` + - `// END SectionName` +- **Java**: + - `// START SectionName` + - `// END SectionName` +- **Go**: + - `// START SectionName` + - `// END SectionName` + +### Code output + +Try to be consistent with the code output in different languages. Instead of language specific objects and terms, try to use primitive values for output. + +## Sidebar configuration + +Most pages need to be manually added to the sidebar configuration to appear in navigation: + +```javascript +// In sidebars.js +{ + type: "doc", + id: "weaviate/index", + label: "Introduction", +}, +{ + type: "category", + label: "Quickstart", + link: { + type: "doc", + id: "weaviate/quickstart/index", + }, + items: ["weaviate/quickstart/local"], +}, +{ + type: "link", + label: "Installation", + href: "https://docs.weaviate.io/deploy", +}, +``` + +### Autogenerated sidebars + +Some sections use autogenerated sidebars that automatically include all files in a directory: + +```javascript +conceptsSidebar: [ + { + type: "autogenerated", + dirName: "weaviate/concepts", + }, +], +``` + +Files in autogenerated sections appear automatically but can be ordered using the `sidebar_position` field in frontmatter. + +:::tip + +Whenever possible try to use autogenerated sidebars. + +::: + +## `CardsSection` Component + +CardsSection creates interactive card layouts for navigation and feature highlighting: + +```jsx +import CardsSection from "/src/components/CardsSection"; + +export const welcomeCardsData = [ + { + id: "new", + title: "New to Weaviate?", + description: ( + <> + Start with the{" "} + Quickstart tutorial – an + end-to-end demo that takes 15–30 minutes. + + ), + link: "/weaviate/quickstart", + icon: "fas fa-star", // Font Awesome CSS class + }, + { + id: "concepts", + title: "Core Concepts", + description: + "Learn about vector databases, embeddings, and how Weaviate works.", + link: "/weaviate/concepts", + icon: "fas fa-brain", + }, +]; + +; +``` + +Each card object supports: + +- **id**: Unique identifier for the card +- **title**: Card heading text +- **description**: Card content (can include JSX) +- **link**: Destination URL (internal or external) +- **icon**: Font Awesome CSS class for the icon + +### Styling options + +Apply custom CSS classes for different card layouts: + +- Default large cards +- `className={styles.smallCards}` - Compact card layout +- Custom CSS classes defined in your component's CSS module + +## `APITable` component + +APITable wraps standard markdown tables to make each row clickable and linkable: + +```mdx +import APITable from "@site/src/components/APITable"; + +; +``` + +import APITable from "@site/src/components/APITable"; + +```mdx-code-block + +``` + +| Parameter | Type | Description | +| ------------ | ------- | ------------------------- | +| `collection` | string | Name of the collection | +| `limit` | integer | Maximum number of results | +| `offset` | integer | Number of results to skip | + +```mdx-code-block + +``` + +Check out the source code of this page for an example of how to use the `APITable` component. + +## Images + +For simple images, use Markdown syntax: + +```markdown +![Simple image](./_includes/image.png) +``` + +### `ThemedImage` component + +For images requiring separate light and dark mode variant or CSS adjustments (e.g. width), use the Docusaurus `ThemedImage` component: + +```jsx +import ThemedImage from "@theme/ThemedImage"; +import MyImageLight from "./_img/my_image_light.png"; +import MyImageDark from "./_img/my_image_dark.png"; + +; +``` + +## Questions and feedback + +import DocsFeedback from "/_includes/docs-feedback.mdx"; + + +``` diff --git a/docs/contributor-guide/weaviate-docs/index.mdx b/docs/contributor-guide/weaviate-docs/index.mdx new file mode 100644 index 00000000..049e5acb --- /dev/null +++ b/docs/contributor-guide/weaviate-docs/index.mdx @@ -0,0 +1,59 @@ +--- +title: Weaviate Documentation +description: Complete guide for contributing to Weaviate's documentation +image: og/contributor-guide/getting-started.jpg +# tags: ['contributor-guide', 'docs'] +--- + +import CardsSection from "/src/components/CardsSection"; + +Welcome to the Weaviate documentation contributor guide! Whether you're fixing typos, adding new tutorials, or improving existing content, this section provides everything you need to contribute effectively to our documentation. + +Our documentation is built with Docusaurus and includes comprehensive guides, API references, tutorials, and examples. Your contributions help thousands of developers understand and use Weaviate more effectively. + +## Quickstart + +1. **Use the [docs repository](https://github.com/weaviate/docs)** on GitHub + - Users should fork the repository + - Weaviate employees don't need to fork the repo and should create a new branch +2. **Set up your local environment** following our [development guide](./development.mdx) +3. **Make your changes** in accordance with our [style guidelines](./style-guide.mdx) +4. **Test locally** with `yarn build` to ensure everything works +5. **Submit a pull request** with a clear description of your changes + +## Documentation guides + +export const docsGuidesData = [ + { + id: "development", + title: "Setup and editing guide", + description: + "Learn how to build docs locally, use components like CardsSection, handle linking, and work with our Docusaurus setup.", + link: "/contributor-guide/weaviate-docs/development", + icon: "fas fa-code", + }, + { + id: "style-guide", + title: "Style guidelines", + description: + "Writing guidelines, tone, formatting standards, and content conventions to ensure consistency across all Weaviate documentation.", + link: "/contributor-guide/weaviate-docs/style-guide", + icon: "fas fa-pen-fancy", + }, + { + id: "llms", + title: "Optimizing docs for LLMs", + description: + "Best practices for making documentation AI-friendly, including content structure, llms.txt implementation, and writing effective frontmatter.", + link: "/contributor-guide/weaviate-docs/llms", + icon: "fas fa-robot", + }, +]; + + + +## Questions and feedback + +import DocsFeedback from "/_includes/docs-feedback.mdx"; + + diff --git a/docs/contributor-guide/weaviate-docs/llms.mdx b/docs/contributor-guide/weaviate-docs/llms.mdx new file mode 100644 index 00000000..dcdb4d25 --- /dev/null +++ b/docs/contributor-guide/weaviate-docs/llms.mdx @@ -0,0 +1,70 @@ +--- +title: Optimizing docs for LLMs +image: og/contributor-guide/welcome.jpg +# tags: ['contributor-guide', 'docs'] +--- + +As AI tools and language models become increasingly important for developers, optimizing our documentation for LLM consumption ensures that users can get accurate, helpful answers when interacting with AI assistants about Weaviate. + +## General LLM optimization guidelines + +- **[Clear heading hierarchy](./style-guide.mdx#formatting--styling-rules)** is essential for LLM comprehension. A well-organized page with logical H1, H2, and H3 headings helps AI models understand the relationships between different sections of your documentation. This structure enables more accurate responses when users ask questions about specific topics. + +- **Consistent formatting** across pages helps LLMs recognize patterns and provide more reliable answers. Use the same heading styles, code block formats, and section organization throughout the documentation. + +- **Self-contained sections** work best for AI processing. Rather than spreading related information across multiple pages or external links, keep relevant content directly in your documentation. LLMs have difficulty parsing linked files and external pages, so inline information provides better context. + +- **Troubleshooting as Q&A** is particularly effective for LLMs since it mirrors the question-and-answer format that users typically employ when interacting with AI assistants. Structure troubleshooting sections with clear questions followed by comprehensive answers. + +- **Include self-standing code snippets** rather than fragments that require context from other sections. This is especially important for products with complex SDKs or APIs, as LLMs can provide more accurate code examples when they have complete, runnable snippets to reference. + +- **Describe visual information in text** alongside screenshots and diagrams. While images can be helpful for human readers, LLMs parse text more efficiently, so ensure that information conveyed through visuals is also available in written form. + +- **[Define acronyms and specialized terminology](./style-guide.mdx#terminology)** within your documentation rather than assuming prior knowledge. This helps LLMs provide more accurate explanations when users ask about technical concepts. + +- **[Use clear, direct language](./style-guide.mdx#content-guidelines)** that focuses on conveying information efficiently. Avoid overly complex sentence structures that might confuse AI models during parsing. + +## `docusaurus-plugin-llms-txt` plugin + +### What is `llms.txt`? + +llms.txt is a proposed standard that provides LLM-friendly content by adding a `/llms.txt` markdown file to websites to offer brief background information, guidance, and links to detailed markdown files. Think of it as a "sitemap for AI" - while robots.txt tells crawlers what to avoid and sitemap.xml provides a basic URL list, llms.txt gives AI models structured, meaningful information about your content. + +### How to use the plugin + +We use the [`@signalwire/docusaurus-plugin-llms-txt`](https://www.npmjs.com/package/@signalwire/docusaurus-plugin-llms-txt) Docusaurus plugin to automatically generate our llms.txt file. The plugin leverages the `description` field from each page's frontmatter to create meaningful summaries in the generated llms.txt file. This means that writing good page descriptions directly improves our AI optimization. + +When you run `yarn build`, the plugin processes all documentation pages and creates the llms.txt file in the `build/llms.txt` directory, making it available at `https://docs.weaviate.io/llms.txt`. The plugin intelligently organizes documents into categories with configurable depth and provides flexible filtering by content type. + +### Best practices for page descriptions + +Since our llms.txt generation relies on frontmatter descriptions, follow these guidelines when writing them: + +```yaml +--- +title: Vector index +description: Learn how to configure vector indexing parameters, choose between HNSW and flat indexing, and optimize performance for your specific use case. +--- +``` + +- **Be specific and actionable**: Describe what users will learn or accomplish, not just what the page covers. +- **Include key concepts**: Mention important terms and concepts that users might search for. +- **Keep it concise but comprehensive**: Aim for 1-2 sentences that capture the page's value and scope. +- **Use consistent terminology**: Match the language and terms used throughout the rest of the documentation. + + + +## Questions and feedback + +import DocsFeedback from "/_includes/docs-feedback.mdx"; + + diff --git a/docs/contributor-guide/weaviate-docs/style-guide.mdx b/docs/contributor-guide/weaviate-docs/style-guide.mdx new file mode 100644 index 00000000..fe099188 --- /dev/null +++ b/docs/contributor-guide/weaviate-docs/style-guide.mdx @@ -0,0 +1,141 @@ +--- +title: Style guidelines +image: og/contributor-guide/welcome.jpg +# tags: ['contributor-guide', 'clients'] +--- + +This style guide provides a framework for creating clear, consistent, and user-friendly documentation for Weaviate. It emphasizes practical guidelines to help you write effectively for our audience. + +--- + +## Content guidelines + +### Audience + +Our documentation serves **AI developers** across various experience levels. When creating quickstart guides, we primarily focus on developers, data scientists, and students, while also considering system evaluators who may be assessing Weaviate for their organizations. We assume readers have **minimal knowledge of vector databases** and provide appropriate context and explanations to help them succeed. + +### Voice & tone + +Address readers directly using **active voice** and the **second person ("you")** to create a personal, engaging experience. Maintain a **conversational, non-academic, and friendly tone** throughout all documentation. Avoid overly formal language that creates distance, but also steer clear of frivolous content that undermines credibility. **Adjust the assumed level of user knowledge** based on the specific page content, providing more foundational explanations in introductory materials and allowing for greater technical depth in advanced topics. + +### Inclusion & accessibility + +Follow **[Google's accessibility guidelines](https://developers.google.com/style/accessibility)** to ensure our documentation remains bias-free and respectful of all users, regardless of their background or identity. Prioritize creating **clear and useful documentation** that serves everyone, including users with disabilities. + +**Key accessibility requirements:** + +- Provide **meaningful alt text** for all images that summarizes their intent (use empty alt text only for purely decorative images) +- Use **descriptive headings and titles** that clearly indicate content structure and purpose + +--- + +## Types of documentation pages + +Categorize content using these types: + +- **Concept:** Explains fundamental ideas and principles. +- **Guides (how-to):** Provides step-by-step instructions to achieve a specific goal. +- **Reference:** Offers detailed information about APIs, configurations, and technical specifications. +- **Tutorial:** Guides users through a complete process, often combining concepts and guides. + +--- + +## Documentation directory structure + +The documentation is organized into key sections. When contributing, understand where your content fits: + +- **Weaviate Database - `/docs/weaviate`:** Contains getting started tutorials, how-to guides for collection management and search operations, integrations with AI model providers, API reference documentation, technical concepts explanations, code examples for common tasks, release notes, performance benchmarks, module documentation, FAQ, glossary, and sample datasets. + +- **Deployment docs - `/docs/deploy`:** Documentation for deploying and operating Weaviate instances. Covers installation methods including Docker and Kubernetes, configuration options for authentication and performance, production deployment patterns, scaling and high availability setups, cloud provider-specific guides, troubleshooting information, and version migration procedures. + +- **Weaviate Agents - `/docs/agents`:** Documentation for Weaviate's agent framework. Includes setup instructions, usage examples, and implementation patterns for building AI agents that can interact with Weaviate databases. + +- **Weaviate Cloud - `/docs/cloud`:** Documentation for Weaviate's managed cloud service. Contains account setup procedures, Weaviate embeddings service documentation, billing and subscription management, service limitations, and cloud-specific configuration options. + +- **Academy - `/docs/academy`:** Educational content and learning materials for Weaviate concepts and implementations. Provides structured learning paths and tutorials for different skill levels. + +- **Integrations - `/docs/integrations`:** Documentation for third-party tools and frameworks that work with Weaviate. Covers client libraries, data import tools, visualization platforms, and other ecosystem integrations. + +- **Contributor guide - `/docs/contributor-guide`:** Documentation for contributing to Weaviate's open source projects. Includes development setup instructions, coding standards, testing procedures, and contribution workflows for the database, modules, client libraries, and contextionary components. + +--- + +## Page layout + +- **Frontmatter:** The `title` and [`description`](./llms.mdx#best-practices-for-page-descriptions) fields are required. +- **Top-level headings:** Do not include redundant top-level headings like `## Introduction` or `## Overview` within the body content; the page title serves this purpose. +- **Related pages:** Place links to related pages at the **bottom of the page** within a `## Further resources` section. +- **QA section:** Most pages should and with a `## Questions and feedback` section. + +--- + +## Formatting & styling rules + +- **Capitalization:** Use **sentence case for all headings**. + - _Example:_ `## This is a heading about Weaviate` +- **Lists:** + - Transform "cascading sentences disguised as lists" into proper lists. + - Use **numbered lists for sequences**. + - Use **bulleted lists for most other lists**. +- **Headings hierarchy:** + - Skip the title heading `#`, the title will be derived from the frontmatter field `title:`. + - Avoid starting pages with heading such as `## Introduction` or `## Overview` (an exception for this are tutorials). + - Use Markdown for headings: `## Section title`, `### Subsection title`, `#### Sub-subsection title`. + - Do not skip heading levels (e.g., go directly from `##` to `####`). + - Be aware that H4 and lower headings will not appear in the right-hand-side table of contents. +- **Code elements:** + - Use **code font** for all code-related text like method names, environment variables, etc. +- **Punctuation:** Use [serial commas](https://developers.google.com/style/commas). +- **American English:** Assume US dialect for English spelling and usage. Write for a global audience. + +--- + +## Terminology + +Use clear, direct language. Define acronyms and abbreviations on first use. At least on the **first mention** of a Weaviate method or term on a page, **link to its corresponding reference, concept page or how-to page**. + +--- + +## Visual assets + +- **Images** + - **Dark/light mode images:** Use the [`ThemedImage` component](./development.mdx#themedimage-component) for specifying both light and dark mode variants of the same image. + - **Social/preview images:** Use the `image:` frontmatter for social media previews and images available in `static/og/`. + - **Screenshots:** Avoid using too many screenshots due to maintenance challenges. An exception to this rule are the [Weaviate Cloud](/cloud) docs where the WCD console needs to be documented visually as well. +- **Diagrams:** Diagrams are acceptable where they add clarity. We use [Excalidraw](https://app.excalidraw.com/) and [Mermaid](https://mermaid.js.org/) (legacy). +- **Videos:** Videos can supplement written documentation but should not replace it. Ensure videos are kept up-to-date as the UI evolves. + +:::info + +Include meaningful alt text for all assets where applicable (images, videos, etc.). + +::: + +--- + +## Versioning + +The Weaviate documentation is not versioned, there is only one official version which is live on [docs.weaviate.io](https://docs.weaviate.io/). + +We indicate which version the feature was introduced in with admonitions: + +- **New generally available (_GA_) features** with a version tag: + +:::info Added in version `vX.Y.Z` +::: + +- New features in **technical preview**, use a caution block to warn users: + +:::caution Technical preview + +`` was added in **`v1.32`** as a **technical preview**.

+This means that the feature is still under development and may change in future releases, including potential breaking changes. +**We do not recommend using this feature in production environments at this time.** + +::: + +## Questions and feedback + +import DocsFeedback from "/_includes/docs-feedback.mdx"; + + diff --git a/docs/contributor-guide/weaviate-modules/_category_.json b/docs/contributor-guide/weaviate-modules/_category_.json deleted file mode 100644 index 237c3a82..00000000 --- a/docs/contributor-guide/weaviate-modules/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Weaviate Modules", - "position": 4 -} diff --git a/docs/contributor-guide/weaviate-modules/architecture.md b/docs/contributor-guide/weaviate-modules/architecture.md index f2572934..9dd95e36 100644 --- a/docs/contributor-guide/weaviate-modules/architecture.md +++ b/docs/contributor-guide/weaviate-modules/architecture.md @@ -1,17 +1,14 @@ --- title: Architecture -sidebar_position: 2 image: og/contributor-guide/weaviate-modules.jpg # tags: ['contributor-guide', 'weaviate module system'] --- -## Architecture (Code Level) - This page describes the code-level architecture. The high-level architecture depends on the respective module. For example, `media2vec` modules typically use a microservice pattern to offload model inference into a separate container, [see this example for the `text2vec-transformers` high-level -architecture](./overview.md#high-level-architecture). +architecture](./index.md#high-level-architecture). ## What is a module (from a Golang perspective?) @@ -114,3 +111,9 @@ Take a look at some of the existing modules to get a feel for how they work: - [`text2vec-contextionary`](https://github.com/weaviate/weaviate/tree/master/modules/text2vec-contextionary) - [`text2vec-transformers`](https://github.com/weaviate/weaviate/tree/master/modules/text2vec-transformers) + +## Questions and feedback + +import DocsFeedback from '/_includes/docs-feedback.mdx'; + + diff --git a/docs/contributor-guide/weaviate-modules/how-to-build-a-new-module.md b/docs/contributor-guide/weaviate-modules/how-to-build-a-new-module.md index e9084a53..fb0303f5 100644 --- a/docs/contributor-guide/weaviate-modules/how-to-build-a-new-module.md +++ b/docs/contributor-guide/weaviate-modules/how-to-build-a-new-module.md @@ -1,7 +1,6 @@ --- title: Module creation in a nutshell label: How to build a custom module -sidebar_position: 3 image: og/contributor-guide/weaviate-modules.jpg # tags: ['contributor-guide', 'weaviate module system', 'custom module'] --- @@ -27,14 +26,14 @@ On this page, you'll find how to create a complete new module (option B), so bui ## Prerequisites -This requires some programming in Golang, since you'll need to build the module for Weaviate, which is written in Go. You don't need to be a very experienced Go programmer, but you'll need some basic understanding of how this statically typed language works. You can view and copy code from other modules to your own project, which is explained later. You'll build a custom module ([part 1 of this image](./architecture.md#visualization)), as well as a custom inference service ([part 2](./architecture.md#visualization)). It is recommended to understand the module architecture of Weaviate which you can read [here](./overview.md) (overview) and [here](./architecture.md) (architecture), before you start building your own module. +This requires some programming in Golang, since you'll need to build the module for Weaviate, which is written in Go. You don't need to be a very experienced Go programmer, but you'll need some basic understanding of how this statically typed language works. You can view and copy code from other modules to your own project, which is explained later. You'll build a custom module ([part 1 of this image](./architecture.md#visualization)), as well as a custom inference service ([part 2](./architecture.md#visualization)). It is recommended to understand the module architecture of Weaviate which you can read [here](./index.md) (overview) and [here](./architecture.md) (architecture), before you start building your own module. If you want to make a pull request to Weaviate with your custom module, make sure to adhere to the [code structure](../weaviate-core/structure.md). ## Design the internal Weaviate Module (part 1) Before you start programming, make sure you have a good design and idea how your module should look like: -1. The name of the module should follow the [naming convention](./overview.md#module-characteristics). For a vectorizer: `2vec--` and other modules: `--`. +1. The name of the module should follow the [naming convention](./index.md#module-characteristics). For a vectorizer: `2vec--` and other modules: `--`. 2. Optional GraphQL [`_additional` property fields](/weaviate/api/graphql/additional-properties.md). Here you can return any new field with data that you would like. Make sure the field name doesn't clash with existing field names, like `id`, `certainty`, `classification` and `featureProjection`, and `_additional` fields of other modules that you activate in the same startup configuration. New `_additional` fields can also have subfields. 3. Optional GraphQL [filters](/weaviate/api/graphql/filters.md). You can make a new GraphQL filter on different levels. If your filter is a 'class-level influencer' that influences which results will be returned, you can introduce it at the `Class` level. Examples are `near`, `limit` or `ask`. If your module would only enhance existing results, you should scope the filter to the new `_additional` property. An example is `featureProjection`. 4. Think about what you or another user should be able to configure to use this Weaviate Module. Configuration can be passed in the Weaviate configuration (e.g. in the [docker-compose.yml file](https://github.com/weaviate/weaviate-examples/blob/4edd6ee767d0e80bca1dd8d982db2378992ddb67/weaviate-contextionary-newspublications/docker-compose.yaml#L24-L29)). @@ -58,7 +57,7 @@ These guidelines follow the example of the [QnA module](https://github.com/weavi ### 1. First files -1. In the `/modules` folder, make a new folder with the name of your module. Make sure to adhere to the [naming convention](./overview.md#module-characteristics). +1. In the `/modules` folder, make a new folder with the name of your module. Make sure to adhere to the [naming convention](./index.md#module-characteristics). 2. Add a file `config.go` ([example](https://github.com/weaviate/weaviate/blob/master/modules/qna-transformers/config.go)). This file describes some configuration of the module to Weaviate. You can copy/paste most of the example file, make sure to adapt the functions' receiver names. 2. Add a file `module.go` ([example](https://github.com/weaviate/weaviate/blob/master/modules/qna-transformers/module.go)). This file describes the module as a whole and its capabilities. You will, again, be able to copy most of an example file to your project. Make sure to define which `modulecapabilities` (from [here](https://github.com/weaviate/weaviate/tree/master/entities/modulecapabilities)) you want to use (this will be explained later). @@ -145,3 +144,9 @@ You can now load in any sample or test dataset. If you only make changes in the #### Passing tests Before you submit your PR, your new module implementation must pass all existing tests and any new tests that you added. How to run tests, [check this page](../weaviate-core/tests.md#run-the-whole-pipeline). + +## Questions and feedback + +import DocsFeedback from '/_includes/docs-feedback.mdx'; + + diff --git a/docs/contributor-guide/weaviate-modules/index.md b/docs/contributor-guide/weaviate-modules/index.md index f5446c7a..38a42428 100644 --- a/docs/contributor-guide/weaviate-modules/index.md +++ b/docs/contributor-guide/weaviate-modules/index.md @@ -1,12 +1,97 @@ --- -title: Weaviate Modules -sidebar_position: 0 +title: Weaviate module system +sidebar_position: 1 image: og/contributor-guide/weaviate-modules.jpg -# tags: ['contributor-guide', 'weaviate module system'] --- -- [Overview and High-Level Architecture](./overview.md) -- [Code-Level Architecture](./architecture.md) -- [How to build a custom module](./how-to-build-a-new-module.md) +import SkipLink from '/src/components/SkipValidationLink' - +The Module system in Weaviate is a way to extend Weaviate's functionality. +Modules often provide access to various machine-learning models which can be +used to turn media into vectors at query and import time. However, that's not +the only thing a module can do; any extension on functionality can be +incorporated into a module. + +The user decides which modules are activated at startup through configuration. +Some modules can be combined with each other, others might be conflicting. In +this case startup will fail. + +## High level architecture + +A module is essentially code which compiles with Weaviate, but a module can +also communicate with other services. We are going through the +`text2vec-transformers` module as an example. + +From a high level, the motivation for a user to enable this module would be to +have their imported data vectorized with a transformer module (e.g. BERT, +etc.). Additionally, at query time, the query string should also be vectorized +in the same way. + +From a tech level this module therefore has to provide some capabilities. See +[Architecture](./architecture.md) for details of what capabilities are and +how a module can provide such a capability. The capabilities we need are: + +- **Vectorizer** The module must be able to turn the text of an object to a + vector at import time. + +- **GraphQLArguments** The module must provide text-specific graphQL-Searcher + arguments, such as `nearText`. Additionally the module needs to hook into the + query process and turn user-specified text into a search-vector which + Weaviate can use for the nearest-neighbor search. + +### What happens when the Vectorizer gets called? + +Weaviate is written in Go and so is the module. But what happens if our model +only has Python bindings? The module can decide to make RPC calls (REST, gRPC, +etc.) to other services. In the case of the `text2vec-transformers` module, the +module also provides a python container which wraps the respective model with +a simple REST API, which it can then call from within the module. + +This split into several containers (often referred to as a microservice +pattern) is not just to abstract programming languages away. We obtain several +other benefits from running the container as a separate service. Most notably: + +- **Hardware requirements** + Neural-network-based models, such as BERT & friends, typically require GPUs + to run efficiently. Weaviate however is very fast on cheap CPU-based + machines. Thus instead of requiring expensive GPU-machines for the entire + setup, we can use GPU-machines only for the model interference part. On + Kubernetes this could be achieved through node affinity, for example. Thus, + even if running on the same cluster, you can schedule your Weaviate pods on + CPU-only nodes and have the inference pods run on GPU-enabled nodes. + +- **Independent scalability** + This separation of concerns allows to scale each concern depending on load. + For example, if you have a read-heavy workload, Weaviate Database might be the + bottleneck. If you have a write-heavy workload with very long objects, model + inference might be the bottleneck. By having these concerns separated, you + can individually scale based on your needs. + +- **Exchangability** + Most transformer models have the same API and usage principles. They only + differ in use case and training data. By having the model inference run in a + separate container, you can quickly exchange models. E.g. from BERT to + DistilRoBERTa - only by exchanging Docker containers. + +## Module characteristics + +A module is a custom code that can extend Weaviate by hooking into specific lifecycle hooks. As Weaviate is written in Go, so module code must also be written in Go. However, some existing modules make use of independent services which can be written in any language, as is often the case with vectorizer modules which bring along model inference containers often written in Python. + +Modules can be "vectorizers" (defines how the numbers in the vectors are chosen from the data) or other modules providing additional functions like question answering, custom classification, etc. Modules have the following characteristics: + +- Naming convention: + - Vectorizer: `2vec--`, for example `text2vec-contextionary`, `image2vec-RESNET` or `text2vec-transformers`. + - Other modules: `--`. + - A module name must be url-safe, meaning it must not contain any characters which would require url-encoding. + - A module name is not case-sensitive. `text2vec-bert` would be the same module as `text2vec-BERT`. +- Module information is accessible through the `v1/modules//` RESTful endpoint. +- General module information (which modules are attached, version, etc.) is accessible through Weaviate's `v1/meta` endpoint. +- Modules can add `additional` properties in the RESTful API and [`_additional` properties in the GraphQL API](/weaviate/api/graphql/additional-properties.md). +- A module can add [filters](/weaviate/api/graphql/filters.md) in GraphQL queries. +- Which vectorizer and other modules are applied to which data classes is configured in the [schema](../../weaviate/manage-collections/vector-config.mdx#specify-a-vectorizer). + +## Questions and feedback + +import DocsFeedback from '/\_includes/docs-feedback.mdx'; + + diff --git a/docs/contributor-guide/weaviate-modules/overview.md b/docs/contributor-guide/weaviate-modules/overview.md deleted file mode 100644 index cb7dd5cc..00000000 --- a/docs/contributor-guide/weaviate-modules/overview.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Overview -sidebar_position: 1 -image: og/contributor-guide/weaviate-modules.jpg ---- - -## Weaviate Module System - -import SkipLink from '/src/components/SkipValidationLink' - -The Module system in Weaviate is a way to extend Weaviate's functionality. -Modules often provide access to various machine-learning models which can be -used to turn media into vectors at query and import time. However, that's not -the only thing a module can do; any extension on functionality can be -incorporated into a module. - -The user decides which modules are activated at startup through configuration. -Some modules can be combined with each other, others might be conflicting. In -this case startup will fail. - -## High level architecture - -A module is essentially code which compiles with Weaviate, but a module can -also communicate with other services. We are going through the -`text2vec-transformers` module as an example. - -From a high level, the motivation for a user to enable this module would be to -have their imported data vectorized with a transformer module (e.g. BERT, -etc.). Additionally, at query time, the query string should also be vectorized -in the same way. - -From a tech level this module therefore has to provide some capabilities. See -[Architecture](./architecture.md) for details of what capabilities are and -how a module can provide such a capability. The capabilities we need are: - -- **Vectorizer** The module must be able to turn the text of an object to a - vector at import time. - -- **GraphQLArguments** The module must provide text-specific graphQL-Searcher - arguments, such as `nearText`. Additionally the module needs to hook into the - query process and turn user-specified text into a search-vector which - Weaviate can use for the nearest-neighbor search. - -### What happens when the Vectorizer gets called? - -Weaviate is written in Go and so is the module. But what happens if our model -only has Python bindings? The module can decide to make RPC calls (REST, gRPC, -etc.) to other services. In the case of the `text2vec-transformers` module, the -module also provides a python container which wraps the respective model with -a simple REST API, which it can then call from within the module. - -This split into several containers (often referred to as a microservice -pattern) is not just to abstract programming languages away. We obtain several -other benefits from running the container as a separate service. Most notably: - -- **Hardware requirements** - Neural-network-based models, such as BERT & friends, typically require GPUs - to run efficiently. Weaviate however is very fast on cheap CPU-based - machines. Thus instead of requiring expensive GPU-machines for the entire - setup, we can use GPU-machines only for the model interference part. On - Kubernetes this could be achieved through node affinity, for example. Thus, - even if running on the same cluster, you can schedule your Weaviate pods on - CPU-only nodes and have the inference pods run on GPU-enabled nodes. - -- **Independent scalability** - This separation of concerns allows to scale each concern depending on load. - For example, if you have a read-heavy workload, Weaviate Database might be the - bottleneck. If you have a write-heavy workload with very long objects, model - inference might be the bottleneck. By having these concerns separated, you - can individually scale based on your needs. - -- **Exchangability** - Most transformer models have the same API and usage principles. They only - differ in use case and training data. By having the model inference run in a - separate container, you can quickly exchange models. E.g. from BERT to - DistilRoBERTa - only by exchanging Docker containers. - -## Module characteristics - -A module is a custom code that can extend Weaviate by hooking into specific lifecycle hooks. As Weaviate is written in Go, so module code must also be written in Go. However, some existing modules make use of independent services which can be written in any language, as is often the case with vectorizer modules which bring along model inference containers often written in Python. - -Modules can be "vectorizers" (defines how the numbers in the vectors are chosen from the data) or other modules providing additional functions like question answering, custom classification, etc. Modules have the following characteristics: -- Naming convention: - - Vectorizer: `2vec--`, for example `text2vec-contextionary`, `image2vec-RESNET` or `text2vec-transformers`. - - Other modules: `--`. - - A module name must be url-safe, meaning it must not contain any characters which would require url-encoding. - - A module name is not case-sensitive. `text2vec-bert` would be the same module as `text2vec-BERT`. -- Module information is accessible through the `v1/modules//` RESTful endpoint. -- General module information (which modules are attached, version, etc.) is accessible through Weaviate's `v1/meta` endpoint. -- Modules can add `additional` properties in the RESTful API and [`_additional` properties in the GraphQL API](/weaviate/api/graphql/additional-properties.md). -- A module can add [filters](/weaviate/api/graphql/filters.md) in GraphQL queries. -- Which vectorizer and other modules are applied to which data classes is configured in the [schema](../../weaviate/manage-collections/vector-config.mdx#specify-a-vectorizer). diff --git a/netlify.toml b/netlify.toml index 323a2995..161eb7aa 100644 --- a/netlify.toml +++ b/netlify.toml @@ -718,3 +718,45 @@ status = 301 from = "/weaviate/config-refs/schema/vector-index" to = "/weaviate/config-refs/indexing/vector-index" status = 301 + +## Contributor guide refactoring + +[[redirects]] +from = "/contributor-guide/getting-started" +to = "/contributor-guide" +status = 301 + +[[redirects]] +from = "/contributor-guide/getting-started/improving-docs" +to = "/contributor-guide/weaviate-docs" +status = 301 + +[[redirects]] +from = "/contributor-guide/getting-started/writing-blogs" +to = "/contributor-guide" +status = 301 + +[[redirects]] +from = "/contributor-guide/getting-started/git-and-github" +to = "/contributor-guide" +status = 301 + +[[redirects]] +from = "/contributor-guide/getting-started/commit-guidelines" +to = "/contributor-guide" +status = 301 + +[[redirects]] +from = "/contributor-guide/weaviate-modules/overview" +to = "/contributor-guide/weaviate-modules" +status = 301 + +[[redirects]] +from = "/contributor-guide/contextionary" +to = "/contributor-guide" +status = 301 + +[[redirects]] +from = "/contributor-guide/contextionary/classification-benchmarks" +to = "/contributor-guide" +status = 301 diff --git a/secondaryNavbar.js b/secondaryNavbar.js index 30fc2e7e..621571d6 100644 --- a/secondaryNavbar.js +++ b/secondaryNavbar.js @@ -151,30 +151,10 @@ const secondaryNavbarItems = { link: "/contributor-guide", links: [ { - label: "Get Started", + label: "Documentation", link: "/contributor-guide", sidebar: "contributorSidebar", }, - { - label: "Weaviate Database", - link: "/contributor-guide/weaviate-core", - sidebar: "contributorCoreSidebar", - }, - { - label: "Weaviate Modules", - link: "/contributor-guide/weaviate-modules", - sidebar: "contributorModulesSidebar", - }, - { - label: "Weaviate Clients", - link: "/contributor-guide/weaviate-clients", - sidebar: "contributorClientsSidebar", - }, - { - label: "Contextionary", - link: "/contributor-guide/contextionary", - sidebar: "contributorContextionarySidebar", - }, ], }, events: { diff --git a/sidebars.js b/sidebars.js index 6d47e205..0ab3269d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1114,50 +1114,68 @@ const sidebars = { }, ], contributorSidebar: [ - { - type: "doc", - id: "contributor-guide/index", - label: "Open-source at Weaviate", - }, { type: "category", - label: "Getting started", + label: "Contributor guide", link: { type: "doc", - id: "contributor-guide/getting-started/index", + id: "contributor-guide/index", }, + collapsed: false, items: [ "contributor-guide/getting-started/suggesting-enhancements", "contributor-guide/getting-started/reporting-bugs", - "contributor-guide/getting-started/improving-docs", - "contributor-guide/getting-started/writing-blogs", - "contributor-guide/getting-started/git-and-github", - "contributor-guide/getting-started/commit-guidelines", ], }, - ], - contributorCoreSidebar: [ { - type: "autogenerated", - dirName: "contributor-guide/weaviate-core", + type: "html", + value: "
", }, - ], - contributorModulesSidebar: [ { - type: "autogenerated", - dirName: "contributor-guide/weaviate-modules", + type: "category", + label: "Weaviate Database", + link: { + type: "doc", + id: "contributor-guide/weaviate-core/index", + }, + items: [ + "contributor-guide/weaviate-core/structure", + "contributor-guide/weaviate-core/cicd", + "contributor-guide/weaviate-core/tests", + "contributor-guide/weaviate-core/setup", + "contributor-guide/weaviate-core/parsing-cross-refs", + "contributor-guide/weaviate-core/support-new-runtime-configs", + ], }, - ], - contributorContextionarySidebar: [ { - type: "autogenerated", - dirName: "contributor-guide/contextionary", + type: "category", + label: "Weaviate Docs", + link: { + type: "doc", + id: "contributor-guide/weaviate-docs/index", + }, + items: [ + "contributor-guide/weaviate-docs/development", + "contributor-guide/weaviate-docs/style-guide", + "contributor-guide/weaviate-docs/llms", + ], }, - ], - contributorClientsSidebar: [ { - type: "autogenerated", - dirName: "contributor-guide/weaviate-clients", + type: "doc", + id: "contributor-guide/weaviate-clients/index", + label: "Weaviate Clients", + }, + { + type: "category", + label: "Weaviate Modules", + link: { + type: "doc", + id: "contributor-guide/weaviate-modules/index", + }, + items: [ + "contributor-guide/weaviate-modules/architecture", + "contributor-guide/weaviate-modules/how-to-build-a-new-module", + ], }, ], cloudSidebar: [