735-improving-fedot-documentation (structure)

[IIaKyJIuH]

Partial improvement.

1. Changed structure of the documentation according to this document
2. Added docstrings to classes/functions/props and improved existing ones
3. Created copy_doc decorator to copy docstrings for logically the same functions
4. Improved code blocks, typings, variables names

[pep8speaks]

Hello @IIaKyJIuH! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2022-08-12 07:39:19 UTC

[IIaKyJIuH]

В этом PR упор делается на изменение структуры всей документации, чем на текст.

Так что не обращайте особо внимание на те докстринги, которые я изменил или добавил, всё равно @DenisSidoren перепишет их

[codecov]

Codecov Report

Merging #804 (0ed6459) into master (072e21c) will increase coverage by 0.27%.
The diff coverage is 95.69%.

@@            Coverage Diff             @@
##           master     #804      +/-   ##
==========================================
+ Coverage   87.09%   87.36%   +0.27%     
==========================================
  Files         184      184              
  Lines       12893    12911      +18     
==========================================
+ Hits        11229    11280      +51     
+ Misses       1664     1631      -33     

Impacted Files	Coverage Δ
...timisers/gp_comp/pipeline_composer_requirements.py	100.00% <ø> (ø)
fedot/core/pipelines/tuning/hyperparams.py	93.87% <ø> (ø)
fedot/core/pipelines/tuning/search_space.py	100.00% <ø> (ø)
fedot/core/visualisation/opt_viz.py	53.45% <0.00%> (ø)
fedot/core/dag/node_operator.py	91.48% <87.50%> (-1.99%)	⬇️
fedot/core/pipelines/pipeline.py	98.23% <90.47%> (+1.12%)	⬆️
fedot/core/dag/graph_operator.py	92.59% <94.87%> (-1.28%)	⬇️
fedot/core/pipelines/node.py	95.69% <95.23%> (-0.07%)	⬇️
fedot/core/dag/graph.py	94.36% <96.29%> (-0.80%)	⬇️
fedot/api/main.py	79.21% <100.00%> (ø)
... and 22 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[nicl-nno]

А в read-the-docs можно посмотреть на собранную версию с этими правками?

[DenisSidoren]

А в read-the-docs можно посмотреть на собранную версию с этими правками?

В rtd настроено автоматическое формирование документации для каждого PR - посмотреть можно в сборках там..

Но и тут, в checks должна появляться ссылка на эту версию документации, возможно, в checks показывается не более 3 записей и это как-то можно поменять в настройках

[nicl-nno]

Идеи по неймингу разделов. Мб ещё какие-то идеи будут, как сделать понятнее и лаконичнее.

[DenisSidoren]

Идеи по неймингу разделов. Мб ещё какие-то идеи будут, как сделать понятнее и лаконичнее.

Classes -> Code structure -> Modules (Units/ Components etc) in details

под Code Structure я бы ожидал увидеть иерархию всего кода, какую-то картинку-дерево

[IIaKyJIuH]

А в read-the-docs можно посмотреть на собранную версию с этими правками?

Ссылка на собранную документацию

[gkirgizov]

Оказывается, что первые и самые общие вопросы оказываются где-то в третьем разделе "Остального". Как что-то необязательное, а не что-то самое общее. Кроме того, раздел "Conceptual" не очень хорошо сообщает, о чем он. Предлагаю объединить Conceptual & Others, переименовать в General и поставить их первым разделом.

[IIaKyJIuH]

Может быть тогда лучше засунуть те вопросы, которые не касаются самого внутреннего устройства (т.е. сейчас все из "Others"), в "Abstract", а "Conceptual" переименовать в "API Usage"?

[gkirgizov]

Abstract вроде ок и пояснее, как если бы это abstract в научной статье.
Насчет API Usage я тоже не против, достаточно очевидно. Вот только текущий вопрос-ответ насчет why feature_name is not supported будто по смыслу не вписывается. Но, наверное, это уже вопрсо к PR с наполнением и не структурой

[nicl-nno]

"под Code Structure я бы ожидал увидеть иерархию всего кода, какую-то картинку-дерево"

А RTD так не умеет в плане иерархии меню? Сделать группировку по модулям было бы довольно удобно

[nicl-nno]

Как альтернативный вариант - вручную выделать несколько высокоуровневых разделов, на который разбить описание интерфейсов классов. API/Pipeline/Optimiser/etc

[nicl-nno]

В целом в этом PR можно влить базовые структурные правки, а раздел modules и проч. уже отдельно менять.