Skip to content

Latest commit

 

History

History
145 lines (95 loc) · 7.38 KB

README.adoc

File metadata and controls

145 lines (95 loc) · 7.38 KB
Raw

Neo4j GraphQL library docs

This repo contains the documentation for the Neo4j GraphQL Library.

Prerequisites

Installation

To install the required packages:

npm i

Generating HTML output

To convert asciidoc source to HTML:

npm run build

Viewing HTML output

To view the built site, launch a local server:

  1. npm start

  2. In a browser tab, go to localhost:8000

Live preview

When you run npm start, the project is monitored for updates to asciidoc files.

If a change to an asciidoc file is detected the site is automatically rebuilt.

Generating asciidoc source files

If you are creating new documentation from scratch, creating all the asciidoc files can be time-consuming. This repo contains a script that you can use to save time by generating skeleton asciidoc files from your navigation.

To use the script, first create your navigation file, or files if your doc set has more than one component. To use the script, all navigation files should have the filename content-nav.adoc. Then, to create the asciidoc source files, run npm run adoc-gen.

For every file that is included as a list item entry in a content-nav.adoc file, an asciidoc file is created in the location specified. For example, if modules/ROOT/content-nav.adoc includes * xref:installation/introduction.adoc[], a file is created at modules/ROOT/pages/installation/introduction.adoc.

The file contents consist of a comment to indicate that the file was generated by the script, and a top level title element. If title text is specified in the entry in the navigation file, that value will be used for the title in the generated file. If no title text is specified, the default title text is taken from the filename, formatted with sentence capitalization.

Configuring your project

You’ll need to update the following for your project

antora.yml

  • name: - replace docs-template with the name of the project as it will appear in the URL https://neo4j.com/docs/<PROJECT_NAME>`, for example 'getting-started', 'cypher-manual'.

  • title: - the title of the manual, for example Getting Started Guide, Cypher Manual. This value is displayed in the breadcrumbs above each page.

  • version: - the version of the content that is generated from the branch containing this antora.yml file.

Optionally, you can add the following attributes:

  • display_version: - Use this attribute when you want the version that is displayed in your content and in the UI to be different from the version that appears in the URL. For example, you might want to use /2.0/ in URLs, but display the version as 2.0-beta in the version selector drop-down.

  • prerelease: - if you publish multiple versions of this project, you can mark a version as being a prerelease, by adding prerelease: true. The content is published alongside the other versions, but does not appear in the drop-down version selector, and is not included when Antora is calculating the default (or 'latest') version in order to resolve links between pages. For more information, see Antora // Docs → Identify a Prerelease Version

preview.yml

Antora uses a playbook to determine what content is included in a site, and the appearance of that content.

In our projects, we use preview.yml as the default playbook name.

Update the start_page attribute to match the value of the name attribute in your antora.yml file.

site:
  start_page: docs-template:ROOT:index.adoc

Update the information for the sitemap extension:

antora:
  extensions:
  - require: "@neo4j-antora/antora-modify-sitemaps"
    sitemap_version: '1.0'
    sitemap_loc_version: 'current'
    move_sitemaps_to_components: true

The antora-modify-sitemaps Antora extension generates sitemaps for Neo4j docs that include information about the current release only, and makes sure those sitemaps are included in the right output folder when the HTML is built. In this example, a sitemap file would be generated at build/site/docs-template/1.0/sitemap.xml. Change the value of sitemap_version to the 'current' release version of your project. For example, Neo4j manuals such as the Getting Started Guide or Cypher Manual use 4.4 as their current version, so for those manuals this is set as sitemap_version: '4.4.

[Optional] Add an 'Edit this page' link

If your repo is public, you can add an Edit this page link to your pages to encourage external contributors, and to provide a quick way for users to suggest changes.

Update the following attribute in your playbook:

asciidoc:
  attributes:
    page-origin-private: false

[Optional] Add a 'preview' note to each page

When we publish preview content to either development or production environments, we prepend an admonition to every page to make it clear that this is preview content, for example, as in Graph Data Science 2.0-preview.

You can use the antora-add-notes extension to add content to your pages. Follow the Usage instructions in the package documentation.

Repository and pull requests

Enable automatic cherry-picking on a PR

To enable automatic cherry-picking on a PR, add the label auto-cherry-pick to it. Without it, the responsible GitHub action is not going to be triggered.

To select the target branches you would like to cherry-pick your PR to, add labels of the following structure: auto-cherry-pick-to-<targetBranch>. For example: auto-cherry-pick-to-6.x to cherry-pick it to the branch 6.x or auto-cherry-pick-to-5.x for the branch 5.x. You may even add new labels for branches that do not have such a label yet.

The feature is triggered by either merging a PR with the auto-cherry-pick label or by adding the auto-cherry-pick label to an already closed and merged PR. In the latter case, ensure that you first add the labels containing the target branches and then finally the auto-cherry-pick label. Otherwise the automation starts without any target branches.

Details

The PRs created by this GitHub action will have their heading prefixed with [Cherry-pick][<targetBranch>]. So, for example, for 6.x as the target branch and some changes as the original PR heading, it results in [Cherry-pick][6.x] some changes as the heading for the cherry-picked PR. In case an assignee was set for the original PR, the cherry-picked PRs will also receive the same assignee. You must add reviewers manually after the cherry-picked PRs have been created.

The creation of cherry-picked PRs can take a few minutes. If you are an assignee of the original PR, you receive an email notification once the cherry-picked PRs have been created. The original PR is updated with a comment that contains links to the newly created cherry-picked PRs.

In case of a merge conflict while cherry-picking to a specific release branch, the branch will be skipped. Information on skipped branches is also included in the comment added to the original PR. In that case you will have to take care of cherry-picking manually and resolve the conflicts. This is not going to influence the other release branches as long as they do not have conflicts.