Files

T

Qiming 26f0a81b65 Rework tool/doc for updating reference docs (#10123 )

* WIP - rework update imported docs

* Rework tool/doc for updating reference docs

This PR reimplement the reference docs generator in Python and fixes
some outdated docs and data:

- Do docs import using Python because the GoLang version of tool has
  some following drawbacks:
  * its not convenient for handling YAML config files
  * it has to be compiled to binaries to run on different platforms
  * for every tiny changes you need to compile a new version and check in
- The reference docs we use in website are actually not coming directly
  from `kubernetes/kubernetes`. Most of them come from the `reference-docs`
  project. The configuration files are thus changed to avoid confusion.
- We have changed the location of generated docs so the default configuration
  files and the docs are updated.

2018-09-21 14:08:50 -07:00

community.yml

Refactor Setup and Imported sections (#9916 )

2018-08-20 08:31:27 -07:00

README.md

Rework tool/doc for updating reference docs (#10123 )

2018-09-21 14:08:50 -07:00

reference.yml

Rework tool/doc for updating reference docs (#10123 )

2018-09-21 14:08:50 -07:00

release.yml

Refactor Setup and Imported sections (#9916 )

2018-08-20 08:31:27 -07:00

update-imported-docs

Rework tool/doc for updating reference docs (#10123 )

2018-09-21 14:08:50 -07:00

README.md

Update imported docs

This script updates the docs files that are generated from other repos. It accepts a YAML file name as its input which can be customized on a per-repo basis.

Requirements

Imported docs must follow these guidelines:

Adhere to the Documentation Style Guide.

Have title defined in the front matter. For example:

---
title: Title Displayed in Table of Contents
---

Rest of the .md file...

Be listed somewhere in a file under the data subdirectory, for example, the data/imported.yml file.
Make sure the PyYAML package is installed:

sudo apt-get install python-pip
pip install PyYAML

Usage

From within this directory, run the following command:

+./update-imported-docs <CONFIG-FILE>

where <CONFIG-FILE> can be any YAML configuration file in this directory.

Configuration file format

Each config file may contain multiple repos that will be imported together. When necessary, you can customize the configuration file by manually editing it. You may create new config files for importing other groups of documents. The following is an example of the YAML configuration file:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Note: generate-command is an optional entry, which can be used to run a given command or a short script to generate the docs from within a repo.

Fixing Links

To fix relative links within your imported files, set the repo config's gen-absolute-links property to true. You can find an example of this in community.yml.