This repository contains documentation for RavenDB.
Please create an issue at our YouTrack.
If you have any questions please visit our community.
You do not need anything special if you wish to modify or update an existing Markdown documentation file. You can even edit them straight on GitHub and submit a pull request.
For more comprehensive changes or additions, you will need:
- Visual Studio 2022
- .NET Framework 4.7.1 Developer Pack
- .NET Core 2.0 & 2.1
- RavenDB 4.2
- Clone the repo
- Open
Raven.Documentation.sln
and build the solution- Visual Studio will warn you of any missing SDKs
- You may need to install them and restart
- Ensure your local RavenDB is up and running (e.g.
https://localhost:8080
)- It needs to be unauthenticated as the docs do not use a certificate
- If you need to change the URL, edit
Raven.Documentation.Web/web.config
and set theServerUrl
setting - Take care not to commit this back to source control
- You can use a Docker version of RavenDB if you are already running an instance for other work.
docker run -p <port>:8080 ravendb/ravendb:4.2-ubuntu-latest
- Adjust forward port as necessary to not conflict
- Set the
Raven.Documentation.Web
as the Startup Project - Run the project (Ctrl-F5 to start without debugging)
- Once running, in the bottom right of the browser, click "Development Tools" and then "Generate Documentation for {version}" (or for all versions)
- If a documentation directory for a specific version does not contain any markdown file related to a documentation page, then all the documentation pages are inherited from the previous documentation version.
- If a documentation directory contains any markdown file for a documentation page (for example - dotnet only), then the parser assumes that the current version has an entirely new set of documents. No document from the previous version is inherited.
This behavior ensures us that we don't show obsolete inherited documents for a documentation version. There is a reason why a new language-specific documentation page was introduced for a doc version (for example, the API was changed). This means that all other languages should be also treated as different from the previous version.
In the case of client-api/data-subscriptions/creation/examples
, we have these files in the directories:
- v4.0: dotnet, java, js
- v4.1: dotnet, java
- v4.2: dotnet
- v5.0: no documents
So for v4.1 the parser assumes that the v4.1 version should support dotnet and java. No document from v4.0 is inherited.
The v5.0 directory does not contain any related document, so the documents are inherited from the previous version. v4.2 contains only dotnet document, so v5.0 will support dotnet only.
In order to fix the missing language page, the related markdown file should be copied from the previous version. The pasted file should be analyzed to indicate what needs to be updated for the current documentation version.
- Add
Documentation/[[version]]/Raven.Documentation.Pages/Raven.Documentation.Pages.csproj
project. Make sure that it references the correct RavenDB nuget packages versions. - Add
Documentation/[[version]]/Samples/csharp/Raven.Documentation.Samples/Raven.Documentation.Samples.csproj
project, similarly as above. - Add version to the
AllVersions
list inRaven.Documentation.Web.Core.ViewModels.DocsVersion
. - Run
scripts/populateDocsJson.ps1
in order to populate the correct directory structure and.docs.json
files in the newly addedRaven.Documentation.Pages
project. Please check the script parameters for details. - Add version to the
RouteConfig.RouteAvailableVersions
constant.
For example, let's say in v4.1 there is a document introduced in the path a/b
. It is present in this location also for v4.2. But in v5.0, it was moved to c/d
.
First, you need to tell each version how to reach the new location for a moved document. This is done by adding document mappings.
In the example described above, you need to add the following mappings:
- in v4.1:
"Mappings": [
{
"Version": 5.0,
"Key": "c/d"
}
]
- in v4.2:
"Mappings": [
{
"Version": 5.0,
"Key": "c/d"
}
]
- in v5.0:
"Mappings": [
{
"Version": 4.1,
"Key": "a/b"
},
{
"Version": 4.2,
"Key": "a/b"
}
]
Basically, both v4.1 and v4.2 need to know where to go to when v5.0 is selected from the version dropdown. The same goes for v5.0 when you want to reach v4.1 or v4.2.
The document bubbling algorithm assumes that each document will be present in the version it was introduced in and in all the consecutive versions. You can explicitly define the last supported version of an article in the given location to stop this behavior.
For this particular example, the article introduced in v4.1 in location a/b
will be present in this location for v4.2, v5.0 etc. Assuming that the article was added to a new location in v5.0, you will end up with two articles: 5.0/a/b
and 5.0/c/d
. This will ignore the defined mappings.
In order to fix this, you need to tell the algorithm that the last supported version for location a/b
is v4.2. You do this by adding the following entries to the related .docs.json
file entries:
"LastSupportedVersion": "4.2"
This will tell the algorithm that it shouldn't generate the documentation page for v5.0 and all consecutive versions.
Important: you need to add the LastSupportedVersion
entry to .docs.json
for each version where a related documentation markdown file exists.
The algorithm skips the LastSupportedVersion
analysis for the entries that don't have the markdown file present in the folder. If there are multiple markdown files for different versions, the algorithm will merge their supported versions. If there is no LastSupportedVersion
entry for a given document page version, the algorithm will assume that all the consecutive versions are supported.
For example, let's assume that there are documentation files in both 4.1/a/b.markdown
and 4.2/a/b.markdown
locations. This means that you need to add the "LastSupportedVersion": "4.2"
entries for both v4.1 and v4.2 .docs.json
files. If you forget to do this for v4.2, the algorithm will assume that there is no supported version cap (for v4.2) and will generate the documentation pages for all consecutive versions.