mirror of https://github.com/docker/docs.git
Merge pull request #11618 from thaJeztah/stub_search
Disable search auto-complete in dev environment, update README and CONTRIBUTING
This commit is contained in:
Usha Mandya
GitHub
commit
2d6c104076
|
|
@ -7,15 +7,7 @@ help. If a reviewer realizes you have based your work on the wrong branch, we'll
|
|||
let you know so that you can rebase it.
|
||||
|
||||
>**Note**: To contribute code to Docker projects, see the
|
||||
[Contribution guidelines](/opensource/).
|
||||
|
||||
### Files not edited here
|
||||
|
||||
Files and directories listed in the `path:` keys in
|
||||
[`.NOT_EDITED_HERE.yaml`](/_data/not_edited_here.yaml) are maintained in other
|
||||
repositories and should not be edited in this one. Pull requests against these
|
||||
files will be rejected. Make your edits to the files in the repository and path
|
||||
in the `source:` key in the YAML file.
|
||||
[Contribution guidelines](/opensource/index.md).
|
||||
|
||||
### Quickstart
|
||||
|
||||
|
|
@ -47,46 +39,6 @@ there.
|
|||
>Do you enjoy creating graphics? Good graphics are key to great documentation,
|
||||
and we especially value contributions in this area.
|
||||
|
||||
### Specific new features for a project
|
||||
|
||||
Our docs cover many projects which release at different times. **If, and only if,
|
||||
your pull request relates to a currently unreleased feature of a project, base
|
||||
your work on that project's `vnext` branch.** These branches were created by
|
||||
cloning `master` and then importing a project's `master` branch's docs into it
|
||||
(at the time of the migration), in a way that preserved the commit history. When
|
||||
a project has a release, its `vnext` branch will be merged into `master` and your
|
||||
work will be visible on [https://docs.docker.com/](/).
|
||||
|
||||
The following `vnext` branches currently exist:
|
||||
|
||||
- **[vnext-engine](https://github.com/docker/docker.github.io/tree/vnext-engine):**
|
||||
docs for upcoming features in the [docker/docker](https://github.com/moby/moby/)
|
||||
project
|
||||
|
||||
- **[vnext-compose](https://github.com/docker/docker.github.io/tree/vnext-compose):**
|
||||
docs for upcoming features in the [docker/compose](https://github.com/docker/compose/)
|
||||
project
|
||||
|
||||
- **[vnext-distribution](https://github.com/docker/docker.github.io/tree/vnext-distribution):**
|
||||
docs for upcoming features in the [docker/distribution](https://github.com/docker/distribution/)
|
||||
project
|
||||
|
||||
- **[vnext-opensource](https://github.com/docker/docker.github.io/tree/vnext-opensource):**
|
||||
docs for upcoming features in the [docker/opensource](https://github.com/docker/opensource/)
|
||||
project
|
||||
|
||||
- **[vnext-swarm](https://github.com/docker/docker.github.io/tree/vnext-swarm):**
|
||||
docs for upcoming features in the [docker/swarm](https://github.com/docker/swarm/)
|
||||
project
|
||||
|
||||
- **[vnext-toolbox](https://github.com/docker/docker.github.io/tree/vnext-toolbox):**
|
||||
docs for upcoming features in the [docker/toolbox](https://github.com/docker/toolbox/)
|
||||
project
|
||||
|
||||
- **[vnext-kitematic](https://github.com/docker/docker.github.io/tree/vnext-kitematic):**
|
||||
docs for upcoming features in the [docker/kitematic](https://github.com/docker/kitematic/)
|
||||
project
|
||||
|
||||
## Collaborate on a pull request
|
||||
|
||||
Unless the PR author specifically disables it, you can push commits into another
|
||||
|
|
|
|||
|
|
@ -63,6 +63,7 @@ RUN set -eu; \
|
|||
sed -i 's#<loc>/#<loc>https://docs.docker.com/#' "${TARGET}/sitemap.xml"; \
|
||||
else \
|
||||
jekyll build --profile -d ${TARGET}; \
|
||||
echo '[]' > ${TARGET}/js/metadata.json; \
|
||||
fi; \
|
||||
find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(<a[^>]* href="\)https://docs.docker.com/#\1/#g' "$i"; done;
|
||||
|
||||
|
|
|
|||
117
README.md
117
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# Docs @ Docker
|
||||
Welcome to the repo for our documentation. This is the source for
|
||||
[https://docs.docker.com/](https://docs.docker.com/).
|
||||
Welcome to the repo for our documentation. This is the source for
|
||||
[https://docs.docker.com/](https://docs.docker.com/).
|
||||
|
||||
Feel free to send us pull requests and file issues. Our docs are completely
|
||||
open source and we deeply appreciate contributions from our community!
|
||||
|
|
@ -11,8 +11,8 @@ open source and we deeply appreciate contributions from our community!
|
|||
- [Files not edited here](#files-not-edited-here)
|
||||
- [Overall doc improvements](#overall-doc-improvements)
|
||||
- [Per-PR staging on GitHub](#per-pr-staging-on-github)
|
||||
- [Build the docs locally](#build-the-docs-locally)
|
||||
- [Read these docs offline](#read-these-docs-offline)
|
||||
- [Build and preview the docs locally](#build-and-preview-the-docs-locally)
|
||||
- [Build the docs with deployment features enabled](#build-the-docs-with-deployment-features-enabled)
|
||||
- [Important files](#important-files)
|
||||
- [Relative linking for GitHub viewing](#relative-linking-for-github-viewing)
|
||||
- [Testing changes and practical guidance](#testing-changes-and-practical-guidance)
|
||||
|
|
@ -82,86 +82,78 @@ the errors that prevented it from building. Review the staged site and amend you
|
|||
commit if necessary. Reviewers will also check the staged site before merging the
|
||||
PR, to protect the integrity of [https://docs.docker.com/](https://docs.docker.com/).
|
||||
|
||||
## Build the docs locally
|
||||
## Build and preview the docs locally
|
||||
|
||||
You have three options:
|
||||
On your local machine, clone this repo:
|
||||
|
||||
1. On your local machine, clone this repo and run our staging container:
|
||||
```bash
|
||||
git clone --recursive https://github.com/docker/docker.github.io.git
|
||||
cd docker.github.io
|
||||
```
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/docker/docker.github.io.git
|
||||
cd docker.github.io
|
||||
docker-compose up --build
|
||||
```
|
||||
Then build and run the documentation with [Docker Compose](https://docs.docker.com/compose/)
|
||||
|
||||
If you haven't got Docker Compose installed,
|
||||
[follow these installation instructions](https://docs.docker.com/compose/install/).
|
||||
```bash
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
The container runs in the background and incrementally rebuilds the site each
|
||||
time a file changes. You can keep your browser open to http://localhost:4000/
|
||||
and refresh to see your changes. The container runs in the foreground, but
|
||||
you can use `CTRL+C` to get the command prompt back. To stop the container,
|
||||
issue the following command:
|
||||
> Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/).
|
||||
> If you don't have Docker Compose installed, [follow these installation instructions](https://docs.docker.com/compose/install/).
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
|
||||
in your web browser to view the docs.
|
||||
|
||||
2. Build and run a Docker image for your working branch.
|
||||
To rebuild the docs after you made changes, run the `docker-compose up` command
|
||||
again. This rebuilds the documentation, and updates the container with your changes:
|
||||
|
||||
```bash
|
||||
DOCKER_BUILDKIT=1 docker build -t docker build -t docker-docs
|
||||
docker run --rm -it -p 4000:4000 docker-docs
|
||||
```
|
||||
```bash
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
After the `docker run` command, copy the URL provided in the container build output in a browser,
|
||||
http://0.0.0.0:4000, and verify your changes.
|
||||
Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
|
||||
in your web browser to view the docs.
|
||||
|
||||
3. Install Jekyll and GitHub Pages on your local machine.
|
||||
|
||||
a. Clone this repo by running:
|
||||
To stop the staging container, use the `docker-compose down` command:
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/docker/docker.github.io.git
|
||||
```
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
b. Install Ruby 2.3 or later as described in [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/).
|
||||
### Build the docs with deployment features enabled
|
||||
|
||||
c. Install Bundler:
|
||||
The default configuration for local builds of the documentation disables some
|
||||
features to allow for a shorter build-time. The following options differ between
|
||||
local builds, and builds that are deployed to docs.docker.com:
|
||||
|
||||
```bash
|
||||
gem install bundler
|
||||
```
|
||||
- search auto-completion, and generation of `js/metadata.json`
|
||||
- google analytics
|
||||
- page ratings
|
||||
- `sitemap.xml` generation
|
||||
- minification of stylesheets (css/style.css)
|
||||
- adjusting "edit this page" links for content in other repositories
|
||||
|
||||
d. If you use Ubuntu, install packages required for the Nokogiri HTML
|
||||
parser:
|
||||
If you want to contribute in these areas, you can perform a "production" build
|
||||
locally.
|
||||
|
||||
```bash
|
||||
sudo apt-get install ruby-dev zlib1g-dev liblzma-dev
|
||||
```
|
||||
To preview the documentation with deployment features enabled, you need to set the
|
||||
`JEKYLL_ENV` environment variable when building the documentation;
|
||||
|
||||
e. Install Jekyll and other required dependencies:
|
||||
```bash
|
||||
JEKYLL_ENV=production docker-compose up --build
|
||||
```
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
```
|
||||
Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
|
||||
in your web browser to view the docs.
|
||||
|
||||
>**Note**: You may need to install some packages manually.
|
||||
|
||||
f. Change the directory to `docker.github.io`.
|
||||
|
||||
g. Use the `jekyll serve` command to continuously build the HTML output.
|
||||
|
||||
The `jekyll serve` process runs in the foreground, and starts a web server
|
||||
running on http://localhost:4000/ by default. To stop it, use `CTRL+C`.
|
||||
You can continue working in a second terminal and Jekyll will rebuild the
|
||||
website incrementally. Refresh the browser to preview your changes.
|
||||
To rebuild the docs after you make changes, repeat the steps above.
|
||||
|
||||
<!--
|
||||
TODO re-enable auto-builds, or push master builds to Docker hub
|
||||
## Read these docs offline
|
||||
|
||||
To read the docs offline, you can use either a standalone container or a swarm service.
|
||||
To see all available tags, go to
|
||||
[Docker Hub](https://docs.docker.com/docker-hub/).
|
||||
To see all available tags, go to [Docker Hub](https://docs.docker.com/docker-hub/).
|
||||
|
||||
The following examples use the `latest` tag:
|
||||
|
||||
|
|
@ -180,6 +172,7 @@ The following examples use the `latest` tag:
|
|||
This example uses only a single replica, but you could run as many replicas as you'd like.
|
||||
|
||||
Either way, you can now access the docs at port 4000 on your Docker host.
|
||||
-->
|
||||
|
||||
## Important files
|
||||
|
||||
|
|
@ -246,7 +239,7 @@ advanced usage. For a basic horizontal tab set, copy/paste starting from this
|
|||
code and implement from there. Keep an eye on those `href="#id"` and `id="id"`
|
||||
references as you rename, add, and remove tabs.
|
||||
|
||||
```
|
||||
```html
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#tab1">TAB 1 HEADER</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab2">TAB 2 HEADER</a></li>
|
||||
|
|
@ -300,4 +293,4 @@ still optimizes the bandwidth during browsing).
|
|||
|
||||
## Copyright and license
|
||||
|
||||
Code and documentation copyright 2017 Docker, inc, released under the Apache 2.0 license.
|
||||
Copyright 2013-2020 Docker, inc, released under the Apache 2.0 license.
|
||||
|
|
|
|||
|
|
@ -11,6 +11,9 @@ exclude: ["_scripts", "404.html", "index.html"]
|
|||
google_analytics: GTM-WL2QLG5
|
||||
polldaddy_id: 8453675
|
||||
|
||||
# Enable search autocompletion (requires metadata.json to be generated)
|
||||
local_search: true
|
||||
|
||||
plugins:
|
||||
- jekyll-redirect-from
|
||||
- jekyll-relative-links
|
||||
|
|
|
|||
|
|
@ -54,18 +54,19 @@
|
|||
scripts happens once the HTML is fully parsed.
|
||||
see https://flaviocopes.com/javascript-async-defer/#with-defer-in-the-head
|
||||
{%- endcomment -%}
|
||||
{%- if page.landing == true -%}
|
||||
{%- if page.layout == 'landing' -%}
|
||||
<!-- landing page scripts -->
|
||||
<script defer src="/js/theme-switcher.js"></script>
|
||||
<script defer src="/js/jquery.js"></script>
|
||||
<script defer src="/js/bootstrap.min.js"></script>
|
||||
<script defer src="/js/search.js"></script>
|
||||
{%- else -%}
|
||||
<script defer src="/js/theme-switcher.js"></script>
|
||||
<script defer src="/js/anchorlinks.js"></script>
|
||||
<script defer src="/js/jquery.js"></script>
|
||||
<script defer src="/js/bootstrap.min.js"></script>
|
||||
<script defer src="/js/docs.js"></script>
|
||||
{%- endif -%}
|
||||
{%- if site.local_search -%}
|
||||
<script defer src="/js/search.js"></script>
|
||||
{%- endif -%}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue