Документация Engee

Руководство для участников разработки

TL;DR: Чтобы принять участие в разработке с помощью запросов на вытягивание, можно найти и просмотреть проблемы с метками wanted feature (требуемая функция) или good first issue (подходящая первая проблема) в репозиториях GitHub подпакетов DynamicalSystems.jl

Конечная цель DynamicalSystems.jl заключается в том, чтобы быть полезной библиотекой для ученых, работающих в области нелинейной динамики, и сделать нелинейную динамику доступной и воспроизводимой.

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

  1. Просто используйте ее. Если вы столкнулись с неожиданным поведением, просто сообщите об этом либо в нашем чате Gitter, либо на странице проблем DynamicalSystems.jl.

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

  3. Вносите изменения в код, решая проблемы. Легче всего справиться с проблемами, имеющими метку good first issue (подходящая первая проблема).

  4. Вносите изменения в код, реализуя новые методы. Это самый замечательный способ внесения улучшений. В отдельных пакетах, формирующих DynamicalSystems.jl, есть множество проблем с тегом wanted feature (требуемая функция), которые могут помочь вам принять участие в разработке.

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

Участие в написании кода

При написании кода необходимо иметь в виду следующие моменты.

  • В целом важна скорость реализации, но не настолько, как ясность реализации. Одним из краеугольных камней DynamicalSystems.jl является наличие понятного и читабельного исходного кода. К счастью, Julia позволяет получить не только идеально читаемый, но при этом еще и супербыстрый код ;) При необходимости добавьте комментарии к коду, чтобы пользователь, которому известен метод, мог сразу понять код.

  • Старайтесь разрабатывать общие, расширяемые функции, а не излишне специализированные для конкретного случая.

  • При работе со строками документации новых методов и систем следуйте соглашениям для строк документации DynamicalSystems.jl. В частности, в первом разделе должны кратко описываться функция, ее позиционные аргументы и возвращаемое значение. В следующем разделе ## Keyword Arguments описываются ключевые слова. В следующем разделе ## Description при необходимости подробно описывается алгоритм. Наконец, необходимо привести ссылки на документы, имеющие отношение к методу. Чтобы получить представление, взгляните на строки документации по lyapunov и lyapunovspectrum.

Стиль строк документации

Строки документации — это самое важное в вашем запросе на вытягивание или коде. Главным приоритетом DynamicalSystems.jl является максимально возможное качество документации и полная прозрачность. Лучший способ достичь этого — использовать хорошие строки документации. В DynamicalSystems.jl рекомендуется структурировать строки документации приведенным ниже образом (эту же рекомендацию мы даем на семинаре Good Scientific Code Workshop).

  1. Четкая сигнатура вызова в синтаксисе кода, включая ожидаемые типы входных данных, если необходимо. Сигнатура вызова должна содержать ТОЛЬКО самую важную информацию, а не подробно перечислять каждое ключевое слово.

  2. Краткое описание функции

  3. [Необязательно] Возвращаемое значение и тип, если они неочевидны.

  4. [Необязательно] Ссылки на связанные функции, если это целесообразно.

  5. [Необязательно] Список именованных аргументов, если таковые присутствуют в функции.

  6. [Необязательно] Подробное обсуждение функциональности, если поведение функции имеет научное значение.

  7. [Необязательно] Ссылки на соответствующие научные работы.

Синтаксис строк документации соответствует протоколу Documenter.jl. См. строку документации по функции Ляпунова и используйте ту же структуру.