LINUX.ORG.RU
ФорумTalks

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

 


0

1

Есть большой проект, больше 200 функций. Текущая документация выглядит так: текстовый файл с расширением .ssf, в нем в начале содержание со ссылками на разделы и хешем для поиска по файлу:

# List of contents
# Index; Chapter;      MD5 Hash for fast search
#   A-1; Description;  b0b33bc113dee07c003c1684774c77df
#   A-2; Syntax;       bdaa8c327f2de569b0c780fe0d83148d
#   A-3; Header;       1685a06bdb4bf8b8c9c2cdfe85436799
#   A-4; Blocks;       28f5e5ea99adec83bea79fe6b024498e
#   B-1;  Tetragon;    770d0ad6470cfc890d477494a0d1ee0a
#   C-1;   Flags;      55ed7c8889ce911482e767e865620bfa
#   C-2;   Position;   e5981589d99f5871f2a90748e5728e62
#   C-3;   Corners;    6588c4b615c3bb0ab3c273e5628a4e62
#   C-4;   Filling;    f1348849480703f885dfdc6d8684be32
#   B-2;  Labels;      757889307369887028c89db5646b73de
#   B-3;  Filters;     63ce5e988d05b1b56577e5a94c98c112
#   A-5; Replacements; 3620457077d901b9949085417f7279fa

А в разделе поблочно описание:

CHAPTER A-1
TITLE Description
HASH b0b33bc113dee07c003c1684774c77df
CONTENT
    STF (Smilo Theme File) contains description of the texture that will be
applied to the object. The object might be a window, button etc.
    Every possible state of the object must be coded in separate files, since
every STF file describes only one texture. That, for instance, might be the
neutral state of the button or backgrounds for all windows.

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

Условие - хочу вставлять схемы (сейчас выглядит вот так):

Texture:         x  y
          rn1 = (2, 3)
                 │  │
 ┌───────────────│──┘
 │               │
 │    0    1   2 │ 3   4   5    6   7   8
 │   ┌───┬───┬───↓───┬───┬───┬───┬───┬───┐   Legend
 │ 0 │   │ ┣━━━ 2px ━━━┫ │   │   │   │   │
 │   ├───┼─╹─┼───┼───┼─╹─┼───┼───┼───┼───┤ A - The 1st vertex of the tetragon
 │ 1 │ ┳━━ A═══════════E═══════════B │   │ B - The 2nd vertex of the tetragon
 │   ├─┃─┼─║─┼───┼───┼───┼───┼───┼─║─┼───┤ C - The 3rd vertex of the tetragon
 │ 2 │ ╹ │ ║ │   │   │   │   │   │ ║ │   │ D - The 4th vertex of the tetragon
 └──→ 3px ─║─┼───┼───┼───┼───┼───┼─║─┼───┤ E - The addtnl. Bezier curve's point
   3 │ ╻ │ ║ │   │   │   │   │   │ ║ │   │ F - The addtnl. Bezier curve's point
     ├─┃─┼─║─┼───┼───┼───┼───┼───┼─║─┼───┤ ═ - Tetragon borders
   4 │ ┃ │ ║ │   │   │   │   │   │ ║ │   │ ━ - Size lines
     ├─┃─┼─║─┼───┼───┼───┼───┼───┼─║─┼───┤ ─ - Pixel grid
   5 │ ┻━━ F │   │   │   │   │   │ ║ │   │
     ├───┼─║─┼───┼───┼───┼───┼───┼─║─┼───┤
   6 │   │ ║ │   │   │   │   │   │ ║ │   │
     ├───┼─║─┼───┼───┼───┼───┼───┼─║─┼───┤
   7 │   │ D═══════════════════════C │   │
     ├───┼───┼───┼───┼───┼───┼───┼───┼───┤
   8 │   │   │   │   │   │   │   │   │   │
     └───┴───┴───┴───┴───┴───┴───┴───┴───┘
    The default values are "(0, 0)".

Т.е. хочу мочь вставлять в документацию svg, таблицы, разделы, подразделы, нормальное форматирование кода.

Не хочу - doxygen.

Что посоветуете?

Let the srach begin.

P.S. На клавиатуре умерла буква «[йа]».

★★

Последнее исправление: JB (всего исправлений: 1)

Ответ на: комментарий от bl

Нет, все время имею проблемы с установкой и настройкой сервера.

sambist ★★
() автор топика

Ну так используй читалку урезанного хэтэмээла с картинками или сделай свой формат с форматированием пробелами.

Napilnik ★★★★★
()

часто документацию приходилось писать через телефон в автобусе, поэтому никаких утилит кроме блокнота не применялось

Очень странное оправдание. Вообще-то все доки так и пишутся, в текстовом редакторе. Зачем было свой формат для этого изобретать?

rst + Sphinx

alpha ★★★★★
()
Ответ на: комментарий от alpha

в текстовом редакторе. Зачем было свой формат для этого изобретать?

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

sambist ★★
() автор топика
Ответ на: комментарий от ZuBB

Не помогло, предлагается маркдаун и его производные. Заливать картинки на внешний сервер не вариант. Плюс с подсветкой кода геморрой.

sambist ★★
() автор топика
Ответ на: комментарий от sambist

Заливать картинки на внешний сервер не вариант

если хотите svg и не хотите ничего никуда заливать то можна html + svg. но это врядли вам понравится

ZuBB ★★★★★
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.