diff options
author | Achilleas Pipinellis <axil@gitlab.com> | 2018-01-29 14:42:43 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2018-01-29 14:58:35 +0300 |
commit | 7680b3f2d0b43ec5fac0ba475b784def919d016c (patch) | |
tree | 7fbf5e23bb864831e6f2d09bb23042c78b2eaa57 /README.md | |
parent | d5f974cb8decde57ae3729050212c2b3da7e244b (diff) |
Simplify README
[ci skip]
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 345 |
1 files changed, 173 insertions, 172 deletions
@@ -2,258 +2,259 @@ # GitLab Documentation -- The [GitLab Documentation](https://docs.gitlab.com) website is generated using [Nanoc](http://nanoc.ws). -- [Writing Documentation](https://docs.gitlab.com/ce/development/writing_documentation.html) -- [Style Guide](https://docs.gitlab.com/ce/development/doc_styleguide.html) -- [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/) +This project hosts the repository which is used to generate the GitLab +documentation website and is deployed to https://docs.gitlab.com. It uses the +[Nanoc](http://nanoc.ws) static site generator. -## Contributing - -Read more in [CONTRIBUTING.md](CONTRIBUTING.md). - -## License +You will not find any GitLab docs content here. All documentation files are +hosted in the respective repository of each product (see the following section). -See [LICENSE](LICENSE). - -## Development - -### Requirements +## Projects we pull from -To preview `docs.gitlab.com` locally, you'll need: +There are currently 4 products that are pulled and generate the docs website: -- Unix -- Ruby 2.4.0 -- Bundler -- Repositories - - GitLab CE - - GitLab EE - - GitLab Multi Runner - - GitLab Omnibus - - GitLab Docs +- [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ee) +- [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce) +- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) -> Note: On Windows, the process described here would be different, but as most of contributors use Unix, we'll go over this process for MacOs and Linux users only. +**NOTE:** +Although GitLab Community Edition is generated, it is hidden from the website +as it's a subset of the Enterprise Edition. We generate it for consistency, +until the [GitLab codebase is unified](https://gitlab.com/gitlab-org/gitlab-ee/issues/2952). -### Installing dependencies +## Contributing -#### Ruby 2.4.0 +Read [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of the Developer +Certificate of Origin + License. -If you don't have Ruby installed in your computer, [install Ruby 2.4.0](https://www.ruby-lang.org/en/documentation/installation/) directly. +To contribute to the content of GitLab docs, see: -If you already have other Ruby versions installed, you can use a Ruby version manager to install Ruby 2.4.0 in your system. +- [Writing documentation](https://docs.gitlab.com/ce/development/writing_documentation.html) +- [Style guide](https://docs.gitlab.com/ce/development/doc_styleguide.html) +- [Community writers](https://about.gitlab.com/community-writers/) -Check your Ruby version with `ruby --version`. +## License -To install multiple Ruby versions on MacOS or Linux, we recommend you use RMV: +See [LICENSE](LICENSE). -- Install [RVM](https://rvm.io/rvm/install) -- Install Ruby 2.4.0 with `rvm install 2.4.0` +## Development under GDK -#### Bundler +See [how to preview the docs changes locally using GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). -[Bundler](https://bundler.io/) is an incredible dependency manager. Install it by running `gem install bundler`. +## Development using this repo -#### Repositories +You can clone and use this repo to preview the website as seen on +https://docs.gitlab.com. -**GitLab Team members:** clone the required repos to your machine. Navigate to the directory you'd like to have them, then clone with SSH: +### Requirements -- GitLab CE: `git clone git@gitlab.com:gitlab-org/gitlab-ce.git` -- GitLab EE: `git clone git@gitlab.com:gitlab-org/gitlab-ee.git` -- GitLab Runner: `git clone git@gitlab.com:gitlab-org/gitlab-runner.git` -- GitLab Omnibus: `git clone git@gitlab.com:gitlab-org/omnibus-gitlab.git` -- GitLab Docs: `git clone git@gitlab.com:gitlab-com/gitlab-docs.git` +Here's what you will need to have: -**GitLab Contributors:** fork each of these projects and clone them to your local computer: +- A Unix/Linux environment +- Ruby 2.4+ +- Bundler -- GitLab CE: https://gitlab.com/gitlab-org/gitlab-ce/ -- GitLab EE: https://gitlab.com/gitlab-org/gitlab-ee/ -- GitLab Runner: https://gitlab.com/gitlab-org/gitlab-runner -- GitLab Omnibus: https://gitlab.com/gitlab-org/omnibus-gitlab -- GitLab Docs: https://gitlab.com/gitlab-com/gitlab-docs +**Note:** +On Windows, the process described here would be different, but as most of +contributors use Unix, we'll go over this process for macOS and Linux users. -### Bring Everything Together +#### Ruby -Now that we have everything required, we need to add symlinks, so GitLab Docs can talk to the remaining repos. +The recommended way is to use a Ruby version manager to install Ruby in your +system. -#### Symlinks +One way is to use RMV: -- In a terminal window, navigate to your local path to where you just cloned GitLab Docs -- Output the path by running `pwd`: +1. Install [RVM](https://rvm.io/rvm/install) +1. Install the latest Ruby: - ``` - $ pwd - /Users/username/dir/gitlab-docs + ```sh + rvm install 2.5.0 ``` -- In a terminal window, navigate to your local path to where you just cloned GitLab CE -- Output the path by running `pwd`: +1. Use the newly installed Ruby: + ```sh + rvm use 2.5.0 ``` - $ pwd - /Users/username/dir/gitlab-ce - ``` - -- Copy the output and create a symlink between GitLab Docs (`content/`) and GitLab CE (`/doc/`), by running `ln -s /Users/username/dir/gitlab-ce/doc /Users/username/dir/gitlab-docs/content/ce`. Of course, adjust the paths according to the output of `pwd`. -- Repeat the process to the other three repos: - - GitLab EE: `ln -s /Users/username/dir/gitlab-ee/doc /Users/username/dir/gitlab-docs/content/ee` - - Runner: `ln -s /Users/username/dir/gitlab-runner/docs /Users/username/dir/gitlab-docs/content/runner` - - Omnibus: `ln -s /Users/username/dir/omnibus-gitlab/doc /Users/username/dir/gitlab-docs/content/omnibus` -- Open GitLab Docs in a terminal window and check if you have all the foour there (`ee`, `ce`, `runner`, `omnibus`): `ls content` - -If they're there, we're good to go! - -### Install Docs dependencies +Check your Ruby version with `ruby --version`. -Now let's make Bundler deal with the dependencies defined in the `Gemfile`: +#### Bundler -- Open GitLab Docs in a terminal window -- Switch to Ruby 2.4.0: `rvm 2.4.0` -- Run `bundle install` +[Bundler](https://bundler.io/) is a Ruby dependency manager. Install it with: -### Preview the Docs website +``` +gem install bundler +``` -- `bundle exec nanoc live` +#### Clone the repositories -This will host the site at `localhost:3000`. Changes will be reloaded automatically using [Guard Nanoc](https://github.com/guard/guard-nanoc). +Since this process will clone a few repositories, it might be a good idea to +create a separate directory to have them all together. For example, let's say +the directory will be under your user's home directory. Open a terminal and +execute: -#### Preview on mobile +```sh +mkdir ~/dev/gitlab +``` -If you want to check how your changes look on mobile devices, you can preview the Docs site with -your own devices, as long as they are connected to the same network as your computer. +Once you do that, navigate to the directory you'd like the repos to be cloned: -To do that, we need to change the IP address Nanoc is serving on from the default `http://127.0.0.1` to your computer's [private IPv4 address](https://www.howtogeek.com/236838/how-to-find-any-devices-ip-address-mac-address-and-other-network-connection-details/). +```sh +cd ~/dev/gitlab/ +``` -Once you know what's your computer's private IPv4, use the flag `-o` with the command -`nanoc live`. For example, let's say your current IPv4 address is `192.168.0.105`: +Then, it's time to clone the needed repositories. -```shell -bundle exec nanoc live -o 192.168.0.105 -``` +1. First of all, clone the docs website repository: -Now, open your mobile's browser and type `http://192.168.0.105:3000`, and you should -be able to navigate through the docs site. This process applies to preview the docs site -on every device connected to your network. + ```sh + ## Using SSH (for members that have Developer access) + git clone git@gitlab.com:gitlab-com/gitlab-docs.git -### Extra Step + ## Using HTTPS (for external contributors) + git clone https://gitlab.com/gitlab-com/gitlab-docs.git + ``` -To pull down the documentation content, run `rake pull_repos`. If you want to force-delete the `tmp/` and `content/` folders so the task will run without manual intervention, run `RAKE_FORCE_DELETE=true rake pull_repos`. +1. Then, clone the repositories you wish to contribute changes to the documentation. + For **GitLab contributors**, that do not have Developer access to the projects, + fork the ones you want (see [projects we pull from](#projects-we-pull-from)) + and then clone them by using your forked version (replace `<username>` with + your own username): -## Projects we pull from + ```sh + ## Using HTTPS (for members that do not have Developer access) -We pull from the following projects: + git clone https://gitlab.com/<username>/gitlab-ce.git + git clone https://gitlab.com/<username>/gitlab-ee.git + git clone https://gitlab.com/<username>/gitlab-runner.git + git clone https://gitlab.com/<username>/omnibus-gitlab.git + ``` -- [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce) -- [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ee) -- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) + For members that have Developer access (usually the **GitLab Team members**), + clone the required repos using SSH: -## Examples and Resources + ```sh + ## Using SSH (for members that have Developer access) -### Open Source Nanoc Sites + git clone git@gitlab.com:gitlab-org/gitlab-ce.git + git clone git@gitlab.com:gitlab-org/gitlab-ee.git + git clone git@gitlab.com:gitlab-org/gitlab-runner.git + git clone git@gitlab.com:gitlab-org/omnibus-gitlab.git + ``` -**NOTE**: We use Nanoc 4.0 which has some significant differences from 3.0, be aware that not all example sites use 4.0. +### Create the content symlinks -- [Nanoc's Website](https://github.com/nanoc/nanoc.ws) -- [GitHub Developer Site](https://github.com/github-archive/developer.github.com) -- [Spree Guides](https://github.com/spree/spree/tree/master/guides) -- [Atom Flight Manual](https://github.com/atom/flight-manual.atom.io) -- [Prometheus Docs](https://github.com/prometheus/docs) +Nanoc expects the Markdown files to be under `content/<slug>`, where `<slug>` +is the slug of each product as defined in [`.nanoc.yaml`](/nanoc.yaml). -### Good Documentation +If you have already cloned the repository (or repositories) you want to +contribute to, you can easily satisfy Nanoc's requirement by symlinking only +the directory that holds the documentation content. -- [SendGrid](https://sendgrid.com/docs) -- [Stripe](https://stripe.com/docs) -- [Stripe API](https://stripe.com/docs/api) -- [CircleCI](https://circleci.com/docs) -- [Heroku](https://devcenter.heroku.com/) -- [Slack](https://get.slack.help/hc/en-us) -- [Slack API](https://api.slack.com/) -- [Kong](https://getkong.org/docs/) +1. Open a terminal and navigate to the directory where gitlab-docs was cloned. +1. For each one of the products, create the symlink: -## Requirements/Goals + ```sh + ln -s ~/dev/gitlab/gitlab-ce/doc ~/dev/gitlab/gitlab-docs/content/ce + ln -s ~/dev/gitlab/gitlab-ee/doc ~/dev/gitlab/gitlab-docs/content/ee + ln -s ~/dev/gitlab/omnibus-gitlab/doc ~/dev/gitlab/gitlab-docs/content/omnibus + ln -s ~/dev/gitlab/gitlab-runner/docs ~/dev/gitlab/gitlab-docs/content/runner + ``` -- [x] Feature parity with the existing [docs.gitlab.com](https://docs.gitlab.com/) -- [x] Use GitLab CI / GitLab Pages for compilation, deployment, and hosting of the Documentation site. -- [x] Sections for Community Edition, Enterprise Edition, GitLab CI, and Omnibus. -- [x] Pull documentation from the repositories mentioned above. -- [ ] Versioned documentation (e.g. switch between documentation for 9.0, 9.1, 9.2, 9.3, "latest", etc.) -- [x] Search the documentation (Can either re-use existing Documentation search functionality or implement search using Algolia or something else? Ideally simple and open source, but it doesn't really matter too much.) -- [x] Link to "Edit on GitLab.com" for every page to encourage contribution. -- [x] Responsive design. +1. Check if the symlinks where successfully created: -### Nice-to-haves + ```sh + ls -la content/ + ``` -- [ ] Some way to embed/package the site inside the Rails app so the documentation can be included with the application itself. This would be nice for users behind firewalls, etc. This _should not_ be handled by Rails itself, as that causes all kinds of problems. It should just be a set of static pages. -- [ ] Some way to export the documentation as PDF/ePub for use offline. -- [ ] Future-proofing for internationalization. -- [x] Tests for working internal links and such. (Nanoc includes this by default!) -- [x] A blog post explaining how we do all this using GitLab, GitLab CI, and GitLab Pages, as well as (almost all?) open source tools. -- [x] Breadcrumbs for navigating between pages. -- [x] Auto-generated Table of Contents for every page. -- [x] Anchor links for every page section. -- [x] Syntax highlighting with Rouge. -- [ ] Auto-generated documentation structure based on YML frontmatter. -- [ ] Version dropdown that links to the current page for that version (if it exists). -- [ ] Automatically generated API documentation. +If they're there, we're good to go! -## Implementation details +**Note:** You can use the `pwd` command when in the terminal to check the +directory path you are currently in and use that output to use with the symlinks +commands above. -### URLs +### Install Nanoc's dependencies -URLs should be in the form of `https://docs.gitlab.com/PRODUCT/LANGUAGE/VERSION/documentation-file-name.html`. +Now let's make Bundler deal with the dependencies defined in the +[`Gemfile`](/Gemfile): -Examples: +1. Open a terminal and navigate to the GitLab Docs repo +1. Switch to Ruby using RVM: -- `https://docs.gitlab.com/ce/en/9-0/documentation-file-name.html` -- `https://docs.gitlab.com/ee/en/9-1/documentation-file-name.html` -- `https://docs.gitlab.com/omnibus/en/9-5/documentation-file-name.html` + ```sh + rvm use 2.5.0 + ``` -Relative paths between documentation pages would need to automatically correct to the right product, language, and version. +1. Run: -### Pulling `docs` directories from the CE, EE, and Omnibus repositories + ```sh + bundle install + ``` -#### Requirements +### Preview the Docs website -- Needs to be able to use Git tags to pull in versions. -- Needs to be performant, can't take a huge amount of time to generate the documentation site. Goal is 15 minutes maximum. -- Fully runnable locally so we can easily test changes locally. +Run the following command to bring the embedded web server up: -#### Possible options +```sh +bundle exec nanoc live +``` -**Submodules**: +This will generate and the site and you will be able to view it in your browser +at <http://localhost:3000>. Any changes you make to either the website or the +content of the docs, will be reloaded automatically. -Include the `docs` directories for each repo in the gitlab-docs repo using submodules. +To preview the site on another port, use: -- Not well-supported by GitLab -- Not sure if submodules can be used to pull down just a directory? +```sh +bundle exec nanoc live -p 3004 +``` -**Artifacts**: +This will generate and the site and you will be able to view it in your browser +at <http://localhost:3004>. -Have the build process for the Docs site pull artifacts down from each repository. +#### Preview on mobile -- Artifacts would need to be hosted long-term by CI. -- Can't generate artifacts exclusively for tags, would be generated for every commit. +If you want to check how your changes look on mobile devices, you can preview +the Docs site with your own devices, as long as they are connected to the same +network as your computer. -**Pull in repositories dynamically** (this is what we went with): +To do that, we need to change the IP address Nanoc is serving on from the +default `http://127.0.0.1` to your computer's +[private IPv4 address](https://www.howtogeek.com/236838/how-to-find-any-devices-ip-address-mac-address-and-other-network-connection-details/). -Pull down the repositories during the build process and splice the docs directories together in the right places for use with the nanoc site. +Once you know what's your computer's private IPv4, use the flag `-o`. For +example, let's say your current IPv4 address is `192.168.0.105`: -**Include the built site in the repository itself**: +```sh +bundle exec nanoc live -o 192.168.0.105 +``` -This is almost definitely out of the question due to how bloated the repository would become and how much of a pain it'd be to maintain this, but it is an option and would make the build process quite a bit faster. +Now, open your mobile's browser and type `http://192.168.0.105:3000`, and you should +be able to navigate through the docs site. This process applies to previewing the +docs site on every device connected to your network. -### Performance +## Contributing to the docs website itself -- Use artifacts to store previous versions of the site so they don't have to be regenerated constantly. -- Nanoc is supposedly quite fast. +If you want to just contribute to the docs website, and not the content, you +can use the following command to automatically pull the docs content in order +to have something to preview: -### Differentiating between CE and EE features +```sh +bundle exec rake pull_repos +``` -One potential problem with having separate docs for CE vs. EE is the inability to easily track differences between the two. Their documentation won't necessarily be kept in-sync and pages that differ between CE and EE may cause conflicts when merging the CE repository into EE. +This will pull all the docs content under the `tmp/` directory and copy it in +`content/`. You can then [preview the website](preview-the-docs-website). -One potential solution to this problem is to include the EE docs inside the CE repository and then label pages as either Universal or EE-only (using frontmatter). The same could be done for specific sections on the page. This has the potential downside of complicating the documentation-writing process for contributors, but arguably the complexity of the CE/EE repositories already exists, so we're not really adding complexity so much as switching its form. +If you want to force-delete the `tmp/` and `content/` folders so the task will +run without manual intervention, run: -The Atom Flight Manual has [the ability to switch between platforms for given pages](http://flight-manual.atom.io/using-atom/sections/atom-selections/), this code could be repurposed for including/excluding features based on whether the documentation is CE or EE ([Source](https://raw.githubusercontent.com/atom/flight-manual.atom.io/4c8f8d14e13b84584fe206e914ea06c6dc2b7a96/content/using-atom/sections/atom-selections.md)). +```sh +RAKE_FORCE_DELETE=true rake pull_repos +``` ## Review Apps for documentation merge requests @@ -263,7 +264,7 @@ merge request: https://docs.gitlab.com/ee/development/writing_documentation.html ## Deployment process We use [GitLab Pages][pages] to build and host this website. You can see -`.gitlab-ci.yml` for more information. +[`.gitlab-ci.yml`](/.gitlab-ci.yml) for more information. We also use [scheduled pipelines](https://docs.gitlab.com/ee/user/project/pipelines/schedules.html) to build the site once an hour. |