Ocean
Там про Sphinx очень однозначные фразы написаны: “Sphinx style is the official Python documentation standard” и дальше в тексте, что это вообще единственный способ иметь классную документацию.

Ну да, там подменяется в тексте понятие “документация к питону как проекту” и “документация к коду на питоне”, якобы это одно и то же. Sphinx - это один из генераторов документации, который выбрали в сообществе, чтобы создавать документацию к питону в разных форматах. Для Sphinx'а нужна разметка, как и для IDE, так как это программа (она не может сама понять, где там что написано; ей нужно показывать - делать метки). Основные критерии выбора таких вспомогательных инструментов для питона как проекта такие: нужно, чтобы в этом инструменте всё было и чтобы этот инструмент был простенький (не требовал долгого изучения, чтобы это не снижало скорость развития проекта). Так же и систему для контроля версий выбирали. Раньше там была Mercurial повсюду. Чтобы коммитить в питон, нужно было Mercurial изучать, Git'а там не было. А сейчас её нет, перешли на Git. Раньше они сидели на своём сайте и хранили репозиторий там (сначала на Mercurial, потом на Git), со временем они переехали на GitHub полностью. Так что там сегодня - одно, завтра - другое. Не факт, что Sphinx завтра останется. А код-то остаётся. И в нём не должно быть следов, что раньше он хранился там, а теперь он хранится тут. Или раньше документация по нему строилась там, а теперь она строится тут. То есть в код не должна проникать никакая внешняя муть, потому что она потом десять раз поменяется, а код будет испещрён разными вот такими прошлыми эффектами.

Вот примеры из самого питона:

Документированный модуль (входит в библиотеку питона)
Недокументированный модуль (входит в библиотеку питона)
Почитай и сравни, что тебе дало информацию и дало возможность работать дальше, не отвлекаясь, а на что нужно идти и документацию открывать - то есть тратить дополнительное время.

Комментарии, где мало что понятно (нужно сидеть со штангенциркулем)
Комментарии, где всё понятно (читаешь, как книжку)
Естественно, запоминаются те комментарии, которые хорошо понятны. А хорошо понимаются те комментарии, которые хорошо написаны. А хорошо написаны те комментарии, которые написаны образно, как в художественной литературе. Попробуй запомнить математическую формулу Стирлинга, например. И попробуй запомнить фразу “вышел заяц на крыльцо почесать себе яйцо”. Просто сравни, как оно по скорости запоминается и как оно потом воспроизводится, в том ли порядке, с теми ли буквами и на тех же местах и так далее.

Ocean
Думаю, что ты догадался, что я оч впечатлилась, уши развесила, себе записала все и в голову отложила.

Да, он тебе ещё скажет, что код на питоне надо обязательно в PyCharm'е писать. У этого парня просто нет своих трансляторов, он не умеет их писать, и поэтому ему нужна PyCharm, которая выполнит за него все эти функции, которые ему нужны, а сам он реализовать их себе не может. PyCharm сдохнет - всё, для этого парня это будет конец света. Он будет искать, куда бы мигрировать, потому что без этого всего он не может ничего делать.

Что принято в сообществе питона, то и делай. А этот парень - он никто. Какой бы он классный ни был, сообщество лучше знает, что нужно питону. Это всё всегда обсуждается десятками человек и на основе этого долгого и всестороннего обсуждения принимается какое-то решение, из которого потом PEP рождается - делается такое объявление в сообществе, что “теперь пишем так”.

Это что касается питона. А если про всё программирование говорить, то идешек для всяких языков дохера и больше. Каждая идешка хочет свой формат. И такой предлагают, и вот такой предлагают. Но вот у тебя код, например, и ты что, при миграции из одной идешки в другую будешь каждый раз транслятор писать? Да, можно прилипнуть к идешке и потом сидеть от неё зависеть радостно. А потом она выпустит обновление, из-за которого придётся уходить с этой идешки. И встанет вопрос “а насколько мой код независим от этой идешки? он вообще без неё может существовать”. Там и окажется, что из-за этих посторонних внедрений компилироваться он может только в ней. А чтобы его отдельно скомпилировать, его надо сначала оттранслировать в независимое состояние, что будет, естественно, не так просто сделать.

py.user.next
Ну да, там подменяется в тексте понятие “документация к питону как проекту” и “документация к коду на питоне”, якобы это одно и то же. Sphinx - это один из генераторов документации, который выбрали в сообществе, чтобы создавать документацию к питону в разных форматах.

Спасибо, теперь стало понятно, что это разное. До этого все было слеплено в голове в одну кучу.
Я думала, что это части одного и того же. Ну типа как у растения: есть подземная часть, есть надземная часть. Ну и что я комментируя код, тем самым создаю документацию. Ну и все ж говорят, что документация должна быть хорошей (хотя это звучит уже как миф, все знают, что должна, что где-то есть идеальная документация, но я так и не поняла где ее почитать и посмотреть). Поэтому я и хотела учиться писать хорошую документацию, понятную для будущих коллег.

py.user.next
Почитай и сравни, что тебе дало информацию и дало возможность работать дальше, не отвлекаясь

Почитала внимательно.
Думаю, что в полной мере пока оценить не могу. Потому что уровень у меня низкий. Я еще ничего как книжку не читаю. Во все вникаю. Но да, уловила отличие. Есть такое, что я гуглить пойду, смотреть примеры, документацию или другие источники. Или перечитываю отдельные места прям по много раз, а другое четко и по делу. Все понятно.
Вот ты пишешь четче и понятнее, чем большинство статей и книг, что я читала. Разницу оч хорошо чувствую

py.user.next
Да, он тебе ещё скажет, что код на питоне надо обязательно в PyCharm'е писать.

Ну я уже поняла, что херней страдала и не очень полезно время потратила. Ну что ж. Научусь на своих собственных ошибках. Хорошо, что наконец-то решилась и вылезла с тупыми вопросами на форум) А то еще так бы 3 года сидела и всякого нахватывалась без толку.
Я раньше думала, что недостаток информации - плохо, но когда столкнулась с переизбытком, то утонула в нем. Разнообразие отвлекает, потому что тысячи книг, каналов, курсов. Низкокачественное и глупости жрали время. Подход к обучению у меня был в корне неверный.

Нужно написать эти программы на языке пайтон с помощью функций:
1.Составить программу для решения приведенного ниже задачи
Придумать и задать входные данные так, чтобы выбор был из 4-7 альтернатив.

Элементы равностороннего треугольника пронумерованы следующим образом: 1 - сторона а, 2 -Радиус R1 вписанной окружности (R1 = a√3 / 6), 3 - радиус R2 описанной окружности (R2 = 2R1), 4-площадь S = a 2√3 / 4. Данный номер одного из этих элементов и его значение. Вывести значения остальных элементов этого треугольника (в том же порядке).

2.Данна матрица mxn. Составить схему алгоритма и программу обработки массива.
Найти среднее арифметическое значение для каждой из строк.

3. Программа создает массив записей с данными о авиарейсы транспортной компании:
номер авиарейса, маршрут, тип самолета, дистанция, продолжительность полета, цена билета. Отсортировать записи по телефону авиарейса и вывести список с ценой билета не выше, чем заданной корустувачем программы.