Better documentation format

[burner1024]

Txt docs aren't really convenient to work with. I was thinking maybe that may be improved? For example, store them in yaml, add a build step that generates markdown and then publish it jekyllized on github pages? Or, maybe readthedocs.

My ulterior motive is to be able to consume it automatically in MLS, and I suppose that'd benefit SFSE too.

[phobos2077]

Which docs do you refer to specifically?

[burner1024]

Sfall opcode list/function notes. Other files are not need for automatic consumption, but I guess it wouldn't hurt to have them with proper markup as well.

And if that goes well, maybe we could do the same for the vanilla function reference in the wiki. It doesn't help to have the doc scattered.

Here's what I have already.

[FakelsHub]

Here's what I have already.

Подождем когда будут описания для всех функций)
Откуда "скопипастил" основу описаний?

[burner1024]

Там практически все и есть. Тырил с SFSE, с вики. Проблема в том, что если нет одного авторитетного источника, то потом описания начинают расходиться - тут одно поправили, там другое. Руками за этим всем не уследить.

[burner1024]

So... no objections?

[phobos2077]

You want to add this yaml to sfall repo? I still don't understand what this has to do with sfall :) Looks like something that belongs to a script editor of some sort, like function descriptions I used for my older version of Sfall Script Editor.

[burner1024]

Well, sfall repo is the authoritative source of information about the functions sfall provides, right? Where else are people supposed to get it from?

All I'm talking about is changing free-style txt format it's published now into a structured, formalized format. Which could look like the yaml file I linked, but not necessary - once it's machine-readable, it's easy to convert/adjust.
And that would profive 2 benefits:

1. Editors (SFSE, SFSE extended, MLS) can consume it automatically instead of copying/updating/deleting doc pieces manually from release notes or elsewhere.
2. If the info is strutured, it doesn't take much effort to generate a web doc that is easy to read and navigate, unlike current wall-of-text/infodump.

[phobos2077]

Well if you can convert it to such format, but also provide some kind of human-readable form of the same info pre-generated (so people can read it right away), that'd be great. Maybe .md format, so it can be viewed directly from github?

[FakelsHub]

Напиши на русском что ты хошешь сделать с этим файлом, где ты его хочешь разместить, а то на на английском вся суть теряется)
Если бы ваш уml содержал все описания я бы его встроил в редактор, а так мне пока нет резона писать поддержку для yml файлов, когда ваш файл содержит все что уже есть в opcodes.txt

[burner1024]

Я предлагаю складывать оригинал описания в yml тут в репозитории sfall (например, как у меня сделано, но можно и более детально разбить), а из него автоматически (travis или что-нибудь такое) генерировать удобную html доку. Ее публиковать либо просто в .md, либо на github pages, обработанную jekyll, либо в readthedocs.

Ну и соответственно будет проще подцеплять в редакторы новые версии.

Скрипт для генерации я написать могу, ну а конкретно по формату и где публиковать - какие у вас предпочтения?

Travis требует доступ к репозиторию, так что либо кому-нибудь с доступом это придется настроить, либо можете меня добавить.

[FakelsHub]

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

Может есть хороший бесплатный визуальный редактор для yml файлов?

[burner1024]

Я имею ввиду писать оригинал в yml, а из него генерировать html/md (ну и txt можно, но зачем).
Видимо надо сделать пример, по-моему идея простая, но то-ли я как-то не так объясняю, то ли что.
Для редактирования я использую VScode, он не то что визуальный, но подсветка есть, мне хватает.

[FakelsHub]

Мне к примеру не комфортно писать в yml из-за дополнительной технической информации которую он содержит, поэтому нужна хорошая бесплатная прога для того чтобы отказать от записи в txt.
вот к примеру строки - name: являются технической, и по сути дублирует detail:
обязательны ли там кавычки? (видимо нет)

[FakelsHub]

ame: attack_complex
"Causes the current object (self – must be a critter) to attempt to attack a critter (who) with various parameters modifying the combat:
        called_shot – 0/1/specific means none/random/specific (head, torso, etc.)
        num_attacks – the # of extra attacks the self object gets before the target
        bonus – the bonus to hit the target on the first turn only
        min_damage – the minimum damage that will be done the first attack
        max_damage – the maximum damage that will be done the first attack
        attacker_results – what state the attacker ends in after the first attack
        target_results – what state the target ends in after the first attack"

called_shot / num_attacks - неиспользуемые аргументы. можешь сделать правку

[phobos2077]

Формата проще чем yaml по-моему нет. Не должно быть большой проблемой дописывать в него новые функции, это все равно не часто происходит. А старые можно какими-нибудь регулярками перегнать. Я изначально так и делал для Sfall Script Editor. В любом случае иметь документацию в структурированном виде удобно, т.к. всегда легко перегнать всё разом в другой формат. Т.е. вернуться к старому формату можно будет в любой момент.

@burner1024 сделай пулл реквест с yaml + md документацией и напиши что нужно в travis прописать вместе с PR.

[burner1024]

Finally got to this. Please check out the preview. The site is sourced from this file.

It's not quite complete yet, bits and pieces are missing, but I want to gather feedback before polishing. Thoughts, comments, suggestions?

[phobos2077]

@burner1024 Man this site looks amazing! 👍

[FakelsHub]

Good.
Для Sfall funcX macros, нужно бы еще под категории сделать, чтобы не все скопом были.

[FakelsHub]

И еще самим названия функций цвет поменять на яркий, а то серый еле видно.

[burner1024]

Я думаю funcX macros просто распихать в соответсптвующие категории. Моддерам же неважно макрос это или нет, главное чтобы работало.
Все, что не попадает в выделенные категории. остается в Other.

Вот с дополнительным раскрашиванием кода посложнее, потому что это делают библиотеки (Rouge). Я назначил синтакс c++, кое-как он разбирает, но не все. Лучшим вариантом было бы сделать пулл реквест для поддержки SSL туда, но это я обещать не могу.

Edit: можно еще взять другую тему jekyll, но это вы сами предлагайте.

[FakelsHub]

не надо макросы тасовать, если трудно реализовать под категории, то тогда прямо на одной странице сделать разделение.
с подсветкой имени надо что-то сделать.

[FakelsHub]

если в html файле сделать обмен классов подсветки для названий (и ключевых слов с++) с class="n" на class="kt" то такие слова как int/void становятся серыми а названия красными. получается хороший контраст.

<div class="language-c++ highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">bool</span> <span class="kt">attack_is_aimed</span><span class="p">()</span>

в сохраненном фале just-the-docs.css можно в ручную сразу для всего поменять цвета для классов.

[burner1024]

Насчет разделения, так или иначе, вся структура сайта должна быть описана в doc.yml. Так как именно ты предлагаешь это прописать?

Если макросы разбивать на отдельные подкатегории, то их будет 15 штук, и 12 из них будут повторять уже существующие - т.е. меню станет в два раза длиннее, и нужную функцию надо будет искать в двух местах вместо одного.
Мне непонятно, какой в этом смысл.

[FakelsHub]

Ок. Только тогда для макросов надо пометку сделать что это макрос.
А как это все работает, и взаимодействует, я что-то понять не могу.
Dark тему пробовал?

[FakelsHub]

А есть ли возможность добавить новые типы такие как ObjectPtr/string чтобы они не выделялись красным?

[burner1024]

Основа сайта в формате jekyll лежит тут. При пуше в выбранную ветку Travis ее чекаутит, с помощью небольшой магии генерирует страницы из yaml, и пушит результат в ветку gh-pages. Гитхаб эту ветку публикует как сайт.

Темную тему не пробовал, классы подсветки инвертировал как ты предложил. Разбором синтаксиса занимается библиотека, так что легкого способа добавить новые слова скорее всего нет.

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

[FakelsHub]

*для макросов надо пометку сделать что это макрос.

[FakelsHub]

Чем ты форматируешь .md файлы, руками в браузере/netepad) или есть спец. софт под это?

[burner1024]

VScode. Yaml тоже им (надо поставить расширение).

[burner1024]

Страница макросов так и называется - макросы.

[burner1024]

Environment Variables

[burner1024]

В общем я туда подставил свой токен и все сбилдилось. Так что у тебя с этим проблема.

[FakelsHub]

Куда ты поставил токен?
И что тупо в надписи GITHUB_TOKEN есть какое-то отличие твоего/моего? Чето непонятно с этим текеном.

[burner1024]

Это переменная окружения. Ты можешь ее удалить и создать заново, подставив свой.

[FakelsHub]

Ты туда вставляешь просто строку GITHUB_TOKEN?
И каким образом это берет токен от тебя если это моя репа)

[FakelsHub]

Епрст. Надо было написать в инструкции, что сгененерированый код надо вставлять. А Travis тупой принимает пустое поле.
Теперь мой токен используется.

[FakelsHub]

Тут новая проблема, сайт не работаeт.

Решил проблему, здесь должен быть указан не "ваш сайт" а путь текущего репозитария.
baseurl: "/sfall-documentation" # the subpath of your site, e.g. /blog

[FakelsHub]

Добавьте если можно в скрипт, чтобы он делал такие лейблы возле имени функции (для пометки что это макрос).
https://pmarsceill.github.io/just-the-docs/docs/ui-components/labels/
макрос get_explosion_damage верните обратно этот макрос не относится к FucnX

Я сделал кое-какие изменния в custom.scss для лучшего восприятия.
Изменил в md файлах у некоторого кода подсветку с с++ на js т.к. она нейтральная.
см. последний коммит у меня.

[FakelsHub]

I made the labels.
I will do some more formatting for .md files, then rearrange the functions, and you can take the files back to you.

[burner1024]

Надо в fucntions.yml размечать тогда, где макросы а где нет.

[FakelsHub]

Я уже пометил, они только в разделе Explosion

[FakelsHub]

Кстати некоторые ссылки некорректны, например зайди в Hooks и проверь.

[burner1024]

Скопировал, поправил там несколько опечаток.

[Lexx2k]

Is it possible to add some sort of comment function or similar to the page? This way we could add notes / point stuff out that should be tweaked, reworked, or just precised. There have been a few moments already where stuff confused me while in the end it was pretty simple and obvious. Or just a way to add more code examples as explanations.

[burner1024]

Is it possible to add some sort of comment function or similar to the page? This way we could add notes / point stuff out that should be tweaked, reworked, or just precised. There have been a few moments already where stuff confused me while in the end it was pretty simple and obvious. Or just a way to add more code examples as explanations.

Easy enough to add with disqus or something like that, but... where'd you seen open source docs with comments? I hadn't, and I think the reason is that's not an efficient way to work on software docs. You can't track a comment, you can't resolve a comment. And they stay there forever. It's gonna turn into a pile of garbage after a while.
Anyone who wants to improve the docs can submit a pull request, anyone who thinks they are unclear or imprecise can open an issue about it.

[FakelsHub]

Кажется это не работает.

[burner1024]

запустится когда в мастер смерджится

[FakelsHub]

Я бы предложил парсить сразу изначальный txt и делать из него md.
т.к. это двойная работа пиши в txt потом в yml (который еще содержит не всю информацию из txt)

[burner1024]

txt ты не распарсишь, потому yml и нужен. А txt надо просто выбросить.

[FakelsHub]

Как это не распарсить, ерунду не говорите, там есть немножко разметки, еще добавить и можно без проблем парсить)

А txt надо просто выбросить.

Вроде NovaRain не хочет их выкидывать)
А мне на это все равно, если у NovaRain есть желание пусть в два файла пишет.
Я в обычный txt, MD-шную разметку добавил, мне этого достаточно.

[burner1024]

Так уже добавили немножко, получился yml.
Я не вижу смысла поддерживать txt, но если кому-то хочется, то мне тоже дела нет.

[FakelsHub]

Кстати "сайт" так и не работает, вернее работает, но отображает какие-то синие полосы на весь экран и сверху в левом углу гиперсссылка и текстом "sfall".
В твоем форке сайт фурычит... что-то ты там не доделал.

[FakelsHub]

такой вид)

[NovaRain]

Yup, it's a known issue. phobos said he'll check what's wrong later.

[FakelsHub]

this is not a problem in phobos, because I have the same thing in the repo.
https://fakelshub.github.io/sfall-wiki/

This is more likely due to the wrong organization, his site works in a different custom domain, as opposed to the default domain .github.io

[FakelsHub]

Удалить нужно все что связано с CNAME файлом и установить правильный базовый путь.

[NovaRain]

Удалить нужно все что связано с CNAME файлом и установить правильный базовый путь.

Oh, OK, now it works, thanks.

[FakelsHub]

Set the link (the right on the main sfall page) to the this site pages.

[NovaRain]

Set the link (the right on the main sfall page) to the this site pages.

I don't have the permission to change that section. I already notified phobos, so he may update it later.