Documentation improvement

gnocchixyz / gnocchi

Timeseries database

Apache License 2.0

300 stars 85 forks source link

Documentation improvement #340

Open Asu4ni opened 7 years ago

Asu4ni commented 7 years ago

I'm feeling that our doc is lacking tons of details and there are so much stuf that one can't figure out until browsing through the codes. I'll give some examples down below, and I'd help adding the content now and then.

the list of things to be improved:

[ ] Glossary: needs more items such as timespan, archive policy rule, resource type, etc. and anchors should be placed for linking.
[ ] Details of each entities: for entities like resource, metric, measure, etc., the relation between them (e.g. resource contains metrics), the attributes of them (e.g. metric has creator) should be explicitly explained, listed and illustrated in a page.
[ ] Aggregation method: a complete list showing all ones and the explanations of them.
[ ] REST API: the usage of each api should be explained in details such as what attribute names are invalid.
[X] Distinguish incoming measures (measure) from processed measures (aggregate).

If I come up more or someone suggests some, I'll update the list.

Asu4ni commented 7 years ago

@jd one question. How can I preview the result of my alterations?

jd commented 7 years ago

@Asu4ni Run tox -e docs-gnocchi.xyz and check doc/build/html for output.

Asu4ni commented 7 years ago

I cloned the repo and ran the tox command. The page was correctly displayed. Afterwards, I modified the rst file and ran the command. The html files were updated (checked the modified time) but the contents were the same. Even if I commited my changes, it still didn't work. I'm digging into the doc of sphinx now, but if someone catches what I've missed, please tell me. Thanks!

Asu4ni commented 7 years ago

The error message of the above problem which might be the cause. Exception: Versioning for this project requires either an sdist tarball, or access to an upstream git repository. It's also possible that there is a mismatch between the package name in setup.cfg and the argument given to pbr.version.VersionInfo. Project name gnocchi was given, but was not able to be found.

jd commented 7 years ago

@Asu4ni ah don't bother, it's likely sphinx versioncontrib give you problems. Just run tox -e docs in your case, that'll be enough.

Asu4ni commented 7 years ago

I think we need to distinguish between 'incoming measures' and 'processed measures'.

I'm considering this because our glossary in the document have the item 'measure'. But it does not explicitly show which one it represents(incoming or processed).

I'd like to gain some thoughts from others' opinion. Mine is that we should use two words for these two concepts. Maybe 'measure' for incoming and 'aggregates' for processed.

Or I simply mistook the concepts. XD

jd commented 7 years ago

You're right @Asu4ni, I think it's a good idea to distinguish both and your terms are good. Go ahead if you want to add those and update the glossary and doc!