Документация на движке MkDocs (material)

[lasteris]

Решил предложить чуть более симпатичный и удобный вариант форматирования документации. По составу я ничего не менял. Если таки что-то задел - поправьте ) В папке .github/workflows/ci.yml лежит конфигурационный файл, настроенный на deploy доки в https://EightM.github.io/JavaBackendStartGuide/ по изменениям из ветки develop.

Как это выглядит можно посмотреть тут. Сделал Fork репозитория и опубликовал документацию для демонстрации ) Когда PR одобрите/отклоните - удалю )

Что это, как это, и какие фичи еще добавить - можно посмотреть в официальной документации. Вдохновился этим, https://fastapi.tiangolo.com/ и этим https://smallrye.io/smallrye-mutiny/2.2.0/

Для локальной разработки/запуска необходим python 3.7+, а сама установка пакета и альтернативы описаны тут. Для запуска локально также необходимы плагины, указанные дополнительно в конфиге mkdocs.yml, не входящие в основной пакет. Сейчас там только mkdocs-git-revision-date-localized-plugin и mike

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

[EightM]

@lasteris Привет! Спасибо за такой большой реквест, проведена отличная работа.

Есть пара вопросов:

1. Я не уверен, что использование иконки Java совместимо с лицензией документации (и что ее можно использовать без разрешения). Учитывая как щепетильно Oracle относится к своим копирайтам я бы заменил ее на что-то нейтральное.
2. Возможно для новых людей будет удобно если в корне будет README в котором кратко описано:
   • что лежит в репозитории
   • как это собрать локально
   • ссылка на готовый сайт

В остальном все хорошо 🙂

[lasteris]

@lasteris Привет! Спасибо за такой большой реквест, проведена отличная работа.

Есть пара вопросов:

1. Я не уверен, что использование иконки Java совместимо с лицензией документации (и что ее можно использовать без разрешения). Учитывая как щепетильно Oracle относится к своим копирайтам я бы заменил ее на что-то нейтральное.

2. Возможно для новых людей будет удобно если в корне будет README в котором _кратко_ описано:

* что лежит в репозитории

* как это собрать локально

* ссылка на готовый сайт

В остальном все хорошо 🙂

Спасибо за такой позитивный ответ 🙂 Насчет иконки, я честно, даже и не знаю что сказать Разузнаю, может быть, придумаю что по нейтральнее поставить. (Она идет в пакете fontawesome, так что я как-то и не подумал, что могут быть проблемы).

По второму пункту внесу правки и новым коммит'ом к этому PR добавлю (но уже не сегодня)

P. S. Вообще, я в конец добавил абзац со ссылкой на вопросы/ответы для подготовки к собеседованиям. Хотелось бы как-то эти 2 репозитория скомбинировать. Получился бы еще более актуальный ресурс в помощь новичкам. Правда я пока не придумал как это провернуть. Пока что, мысль просто так и оставить ссылку, но также владельцам того репозитория PR с подобной правкой реализовать ))

[lasteris]

@EightM готово, смотрите что вышло )

[EightM]

@lasteris Спасибо!