[oneDAL] build warnings fix

[michael-smirnov]

This PR fixes problem #147 and all other warnings from oneDAL component:

• All warnings in glossary section fixed
• All warnings in data management section fixed
• Fixed bullet list indentations in introduction section

Warnings produced by case-sensitive checks are resolved this way:

1. When the term mentioned has the name exactly as in the glossary, it is started from the capital letter
2. If the term does not exactly matches to the related glossary section, it is started from lowercase letter.

Example:

• To filter and normalize Feature values that are being extracted
• It is an in-memory or out-of-memory tabular view of data, where
  table rows represent the observations and columns
  represent the features.

Compiled version: https://michael-smirnov.github.io/oneapi-spec/elements/oneDAL/source/index.html

[michael-smirnov]

@rlnx @outoftardis what`s your opinion about this fix? Do we want to make it more consistent and refer to the terms always starting with capital or lowercase letter?

[outoftardis]

I don't think it's a good idea to use capitalized terms in text. I provided a possible solution in the related issue.

[michael-smirnov]

@outoftardis does it mean that I should not use capitalized references at all? There are some references to the topic sections, like "Dataset". When I somewhere else give a reference to this topic, it will be capitalized. Should I make lowercase aliases for such references?

[rlnx]

I don't think it's a good idea to use capitalized terms in text.

Agree with @outoftardis, capitalized word in the middle of the text seems odd to me.

I provided a possible solution in the related issue.

Suppressing all the warnings related to the terms is also not very safe, as it could hide the real warning about missing term.

[rlnx]

@michael-smirnov, the best solution, probably, is to create custom role for Sphinx that would automatically add reference to the capitalized term. It should allow using non-capitilized text, but insert terms as if it was capitilized.

:capterm:`feature`

[rlnx]

Shouldn't be difficult to implement:

from docutils import nodes

def setup(app):
    app.add_role('capterm', capterm_role)

def capterm_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    node = nodes.term(rawtext, text.title()) 
    return [node], []

This can be added here. I'm not 100% sure the code snippet above is working as expected 😄. I used docutils reference from here.

[michael-smirnov]

@rlnx @outoftardis you don't answer the main question - how to deal with links to a document sections? They are capitalized, for example:

Logically, a table is a Dataset with n rows and p columns. Each row represents an observation and each column is a feature of a dataset.

Here Dataset is a link to the corresponding section, but feature is a link to the glossary term.
Do you think we should also fix links to the sections and do not use capitalized links at all?

[michael-smirnov]

Here we also have a term dataset. Do we want to distinguish cases when I refer to the dataset section and to the glossary term "dataset"? Or we should introduce some simple rule, e.g. reference always to the section if exists.

[rlnx]

@rlnx @outoftardis you don't answer the main question - how to deal with links to a document sections? They are capitalized, for example:

@michael-smirnov, I prefer to avoid the capitalized links at all as I said previously.

Here we also have a term dataset. Do we want to distinguish cases when I refer to the dataset section and to the glossary term "dataset"? Or we should introduce some simple rule, e.g. reference always to the section if exists.

Simple rule would be to refer the Dataset section always.

[rlnx]

Implemented custom role approach in #160

[michael-smirnov]

Closed because the better approach is proposed in #160