From 4b87b1f89c9b38a42ba4991210236b6279047cc9 Mon Sep 17 00:00:00 2001 From: Gaurav Jain Date: Sat, 12 Dec 2015 09:01:11 +0000 Subject: [PATCH] Documentation fixes Group certain pages and fix up MkDocs config --- README.md | 37 ++++++------------- docs/{ => Development}/Coding-Standards.md | 11 ++++-- docs/FAQ.md | 6 +-- docs/{ => Getting-Started}/Configuration.md | 16 ++++---- .../Custom-Collectors.md | 0 .../Example-Userscripts.md | 0 docs/{ => Getting-Started}/Facet.md | 0 docs/{ => Getting-Started}/Installation.md | 0 docs/{ => Getting-Started}/Usage.md | 0 docs/Home.md | 5 --- docs/Related-Projects.md | 8 ++-- docs/index.md | 1 + docs/mkdocs.yml | 2 - mkdocs.yml | 4 ++ 14 files changed, 38 insertions(+), 52 deletions(-) rename docs/{ => Development}/Coding-Standards.md (96%) rename docs/{ => Getting-Started}/Configuration.md (97%) rename docs/{ => Getting-Started}/Custom-Collectors.md (100%) rename docs/{ => Getting-Started}/Example-Userscripts.md (100%) rename docs/{ => Getting-Started}/Facet.md (100%) rename docs/{ => Getting-Started}/Installation.md (100%) rename docs/{ => Getting-Started}/Usage.md (100%) delete mode 100644 docs/Home.md create mode 120000 docs/index.md delete mode 100644 docs/mkdocs.yml create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index c1ec8c7d1..9103661e7 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,16 @@ -[![Build Status](https://travis-ci.org/python-diamond/Diamond.svg?branch=master)](https://travis-ci.org/python-diamond/Diamond) -About -===== - -Diamond is a python daemon that collects system metrics and publishes them to -[Graphite](https://github.com/python-diamond/Diamond/wiki/handler-GraphiteHandler) -(and [others](https://github.com/python-diamond/Diamond/wiki/Handlers)). It is -capable of collecting cpu, memory, network, i/o, load and disk metrics. Additionally, -it features an API for implementing custom collectors for gathering metrics from almost any source. +# Diamond -The documentation can be found on our [wiki](https://github.com/python-diamond/Diamond/wiki). For your -convenience the wiki is setup as a submodule of this checkout. You can get it via running +[![Build Status](https://travis-ci.org/python-diamond/Diamond.svg?branch=master)](https://travis-ci.org/python-diamond/Diamond) - git submodule init - git submodule update +Diamond is a python daemon that collects system metrics and publishes them to [Graphite](handlers/GraphiteHandler) (and others). +It is capable of collecting cpu, memory, network, i/o, load and disk metrics. +Additionally, it features an API for implementing custom collectors for gathering metrics from almost any source. -Getting Started -===== +## Getting Started Steps to getting started: - * Read the [documentation on the Wiki](https://github.com/python-diamond/Diamond/wiki) + * Read the [documentation](http://diamond.readthedocs.org) * Install via "pip install diamond". The releases on github are not recommended for use. Use "pypi-install diamond" on Debian/Ubuntu systems with python-stdeb installed to build packages. * Copy the "diamond.conf.example" file to "diamond.conf". @@ -27,14 +18,12 @@ Steps to getting started: * Modify "diamond.conf" for your needs. * Run diamond with one of: "diamond" or "initctl start diamond" or "/etc/init.d/diamond restart". -Success Stories -===== +## Success Stories * Diamond has successfully been deployed to a cluster of 1000 machines pushing [3 million points per minute](https://answers.launchpad.net/graphite/+question/178969). * Have a story? Please share! -Repos -===== +## Repos Historically Diamond was a brightcove project and hosted at [BrightcoveOS](https://github.com/brightcoveos/Diamond). However none of the active developers are brightcove employees and so the development @@ -42,11 +31,9 @@ has moved to [python-diamond](https://github.com/python-diamond/Diamond). We req that any new pull requests and issues be cut against python-diamond. We will keep BrightcoveOS updated and still honor issues/tickets cut on that repo. -Diamond Related Projects -===== - * [Related Projects](https://github.com/python-diamond/Diamond/wiki/Related-Projects) +## Diamond Related Projects + * [Related Projects](Related-Projects) -Contact -===== +## Contact * IRC [#python-diamond](irc://chat.freenode.net:6667/%23python-diamond) on [freenode](http://www.freenode.net). [Webchat](http://webchat.freenode.net/?channels=python-diamond) * Mailing List [diamond@librelist.com](mailto:diamond@librelist.com) - Email the list and you will automatically subscribe. [Archive](http://librelist.com/browser/diamond/) diff --git a/docs/Coding-Standards.md b/docs/Development/Coding-Standards.md similarity index 96% rename from docs/Coding-Standards.md rename to docs/Development/Coding-Standards.md index 1e8115408..a5c7d8cca 100644 --- a/docs/Coding-Standards.md +++ b/docs/Development/Coding-Standards.md @@ -1,11 +1,14 @@ # Coding Standards -## Current +## General - * Collector default configuration should be in the get_default_config method of the class - * All collectors should verify before doing. For example, if the collector requires the existence of a file, check to verify that it exists and is readable before opening. * Unit tests are highly recommended * PEP-8 * Documentation should be done docstr style at the start of the collector. This is how we generate the wiki - * use small high-resolution units as default (such as bits or bytes). this gives you most options afterwards. note that graphite will show k/M/G etc prefixes by default if needed. * The use of positional arguments for functions is strongly discouraged. + +## Collectors + + * Collector default configuration should be in the get_default_config method of the class + * All collectors should verify before doing. For example, if the collector requires the existence of a file, check to verify that it exists and is readable before opening. + * use small high-resolution units as default (such as bits or bytes). this gives you most options afterwards. note that graphite will show k/M/G etc prefixes by default if needed. diff --git a/docs/FAQ.md b/docs/FAQ.md index 5aa15ccb6..3263fe4ef 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,8 +1,6 @@ -FAQ -===== +# FAQ -Why am I missing metrics? -------------------------- +## Why am I missing metrics? Graphite has a configuration variable called `MAX_CREATES_PER_MINUTE`, which prevents the carbon server from creating too many whisper files at once. diff --git a/docs/Configuration.md b/docs/Getting-Started/Configuration.md similarity index 97% rename from docs/Configuration.md rename to docs/Getting-Started/Configuration.md index bcd3ba845..87ee6f83f 100644 --- a/docs/Configuration.md +++ b/docs/Getting-Started/Configuration.md @@ -1,5 +1,6 @@ -Configuration -===== +# Configuration + +## Configuration File If you've installed diamond via a package, a example configuration file is /etc/diamond/diamond.conf.example. Please copy this to /etc/diamond/diamond.conf and configure at will. By default, diamond @@ -19,8 +20,7 @@ We also have diamond-setup. It will walk you though setting up diamond and it's If you have any questions at all, please feel free to stop by and talk to us on irc, [#python-diamond](irc://chat.freenode.net:6667/%23python-diamond) on [freenode](http://www.freenode.net). [Webchat](http://webchat.freenode.net/?channels=python-diamond) -Logging -===== +## Logging Diamond defaults to logging at /var/log/diamond/diamond.log @@ -62,8 +62,7 @@ format = [%(asctime)s] [%(threadName)s] %(message)s datefmt = ``` -Collector Settings -===== +## Collector Settings Every collector has some default options @@ -83,8 +82,7 @@ Every collector has some default options * uname_rev = uname -r in reverse (com.example.www) * none = no hostname autodetection. just use the statically defined hostname -Enable / Disable Collector -=== +## Enable / Disable Collector Diamond collectors that require a separate configuration file should place a .conf file in /etc/diamond/collectors/. @@ -113,4 +111,4 @@ diamond-setup -C HttpdCollector You can add more settings for the Collector in the same file. -Make sure to restart diamond daemon and wait at least 3 collection cycles. \ No newline at end of file +Make sure to restart diamond daemon and wait at least 3 collection cycles. diff --git a/docs/Custom-Collectors.md b/docs/Getting-Started/Custom-Collectors.md similarity index 100% rename from docs/Custom-Collectors.md rename to docs/Getting-Started/Custom-Collectors.md diff --git a/docs/Example-Userscripts.md b/docs/Getting-Started/Example-Userscripts.md similarity index 100% rename from docs/Example-Userscripts.md rename to docs/Getting-Started/Example-Userscripts.md diff --git a/docs/Facet.md b/docs/Getting-Started/Facet.md similarity index 100% rename from docs/Facet.md rename to docs/Getting-Started/Facet.md diff --git a/docs/Installation.md b/docs/Getting-Started/Installation.md similarity index 100% rename from docs/Installation.md rename to docs/Getting-Started/Installation.md diff --git a/docs/Usage.md b/docs/Getting-Started/Usage.md similarity index 100% rename from docs/Usage.md rename to docs/Getting-Started/Usage.md diff --git a/docs/Home.md b/docs/Home.md deleted file mode 100644 index 640611a40..000000000 --- a/docs/Home.md +++ /dev/null @@ -1,5 +0,0 @@ -Diamond is a python daemon that collects system metrics and publishes them to Graphite or other supported handlers. -It is capable of collecting cpu, memory, network, i/o, load and disk metrics. Additionally, -it features an API for implementing custom collectors for gathering metrics from almost any source. - -## [Contributors](https://github.com/python-diamond/Diamond/graphs/contributors) diff --git a/docs/Related-Projects.md b/docs/Related-Projects.md index 00a925820..1e3ddbdcf 100644 --- a/docs/Related-Projects.md +++ b/docs/Related-Projects.md @@ -1,7 +1,9 @@ -Diamond Related Projects -===== +# Related Projects + +## Integrations + * [puppet-diamond](https://github.com/vimeo/puppet-diamond) - diamond module for puppet * [chef-diamond](https://github.com/CBarraford/diamond_cookbook) - diamond cookbook for chef (Reported Broken) * [chef-diamond](https://github.com/damm/diamond) - Alternative diamond cookbook for chef (Reported Broken) * [graph-explorer](https://github.com/Dieterbe/graph-explorer) - graphite dashboard that comes with templates for diamond plugins - * [graph-index](https://github.com/huoxy/graph-index) - index of graphs for diamond \ No newline at end of file + * [graph-index](https://github.com/huoxy/graph-index) - index of graphs for diamond diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 000000000..32d46ee88 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index 74588b245..000000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,2 +0,0 @@ -pages: -- Home: Home.md diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..1b1b82941 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,4 @@ +site_name: Diamond +repo_url: https://github.com/python-diamond/diamond +include_next_prev: false +theme: mkdocs