The VMware Spring Cloud Data Flow for Kubernetes documentation is now published on docs.vmware.com. See below for information about how the documentation is stored and published and about the toolchain we now use.
We no longer use:
-
The "book" repository (https://github.com/pivotal-cf/docs-book-scdf-k8s)
-
Bookbinder
-
The Concourse pipeline (https://runway-ci.eng.vmware.com/teams/mapbu-docs/pipelines/cf-services?group=scdf-k8s)
-
The Pivotal Docs staging website (https://docs-pcf-staging.sc2-04-pcf1-apps.oc.vmware.com/scdf-k8s)
-
The Pivotal Docs production website (https://docs.pivotal.io/scdf-k8s)
You will need:
-
The docs content repository (https://github.com/pivotal-cf/docs-spring-cloud-dataflow-k8s). Note that this is NOT the "book" repository
-
The Markdown Local Preview CLI utility (if you want to view your changes locally)
-
Access to DocWorks (https://docworks.vmware.com/)
-
Access to the Docs Dashboard (https://docsdash.vmware.com/)
Complete steps:
-
Edit content files locally
-
Preview your changes locally
-
Commit and push your changes to GitHub
-
In DocWorks, publish the docs to staging
-
Review your changes on staging
-
In Docs Dashboard, promote your changes to pre-production
-
In Docs Dashboard, sign off on your changes in pre-production
-
In Docs Dashboard, promote your changes to production
For more information, see the following sections.
All content files are stored in the content repository on GitHub (https://github.com/pivotal-cf/docs-spring-cloud-dataflow-k8s). Clone this repository.
To edit documentation, check out the relevant branch, make changes locally, preview if desired (see the next section), then commit and push your changes. For example, to edit documentation for Spring Cloud Data Flow version 1.4, check out and commit changes to the v1.4 branch.
To preview your changes locally, you must install the Markdown Local Preview CLI utility. For more information and the file download link, see Using the Markdown Local Preview CLI Utility on Confluence.
After installing the utility, follow these steps to prepare for local previews:
-
From the utility directory (for example,
~/Downloads/VMware.GTIX.MarkdownCLI-osx-x64-1.0-0.markdown-cli-osx/Markdown-Cli/), run theMarkdown-Cliutility:$ ./Markdown-Cli
-
Select
Build Project (watches for changes), then press Enter. -
Enter the complete path to the docs content repository on your local machine. For example:
/Users/bobcratchit/Work/docs-spring-cloud-dataflow-k8s
-
Type
n, then press Enter. -
Press any key.
-
Select
Back, then press Enter. -
Select
Exit, then press Enter. -
In your IDE or text editor, open the newly-generated file
_md-cli/dist/config.json. -
Set
tocLocationtotoc.md. -
Set
variablesLocationtovariables.yml.
Now you can preview your changes:
-
From the utility directory, run the
Markdown-Cliutility:$ ./Markdown-Cli
-
Select
Build Project (watches for changes), then press Enter. -
Enter the complete path to the docs content repository on your local machine. For example:
/Users/bobcratchit/Work/docs-spring-cloud-dataflow-k8s
-
Type
y, then press Enter. -
In a browser, open the
DocsPreview.htmlfile that the utility generated under a_md-clisubdirectory of the content repository directory. The file path will be something like the following:/Users/bobcratchit/Work/docs-spring-cloud-dataflow-k8s/_md-cli/dist/DocsPreview.html
-
Navigate to the page that you edited.
-
If you make additional changes, the utility will automatically regenerate the preview. You will have to refresh the preview page in your browser, then navigate to your edited page again.
To publish your changes on the staging website:
-
Visit DocWorks (https://docworks.vmware.com/).
-
Log in using your VMware LDAP credentials.
-
From the main navigation menu, select Markdown.
-
In the left-hand navigation menu, under Markdown Projects, click All.
-
Search for the docs set (for example, "Spring Cloud Data Flow").
-
Locate the "card" for the docs set and click Publish.
NoteDepending on the project, you may see Build and Deploy buttons instead of a Publish button. If so, first click Build, then when the build has finished, click Deploy. -
If the build fails, click the red bar representing the most recent build and review the logs for any warnings or errors. Resolve any errors and start a new build.
-
When the build succeeds, visit the Docs Dashboard (https://docsdash.vmware.com/).
-
Log in using your VMware LDAP credentials.
-
From the main navigation menu, select Deployment > Stage.
-
In the list of deployments, locate the project and click its link in the Publication column. This will take you to the staging website, where you can view your changes.
When you are satisfied with your changes on staging:
-
Return to the Docs Dashboard.
-
In the list of deployments, select your project (select the checkbox in the Product column).
-
Click the Deploy Selected to Pre-Prod button.
-
In the Deployment Status dialog, click Refresh to update the status of the deployment. When the deployment has succeeded, click Hide.
-
From the main navigation menu, select Deployment > Pre Prod.
-
In the list of deployments, locate the project and click its link in the Publication column. This will take you to the pre-production website, where you can view your changes.
When you are satisfied with your changes in pre-production:
-
Return to the Docs Dashboard.
-
In the list of deployments, select your project in the Product column).
-
Click the Sign-Off For Release button.
-
Confirm your sign-off.
-
In the list of deployments, select your project again.
-
Click the Deploy Selected to Prod button.
-
Confirm that you want to deploy to production.
-
In the Deployment Status dialog, click Refresh to update the status of the deployment. When the deployment has succeeded, click Hide.
-
From the main navigation menu, select Deployment > Production.
-
In the list of deployments, locate the project and click its link in the Publication column. This will take you to the production website, where you can view your published changes.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent