Skip to content

TDB (iproto): restructure the docs #4072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
5 tasks done
Tracked by #4002
xuniq opened this issue Feb 29, 2024 · 0 comments
Closed
5 tasks done
Tracked by #4002

TDB (iproto): restructure the docs #4072

xuniq opened this issue Feb 29, 2024 · 0 comments
Assignees
Labels
restructure Related to the transfer of sections, text. TDB

Comments

@xuniq
Copy link
Contributor

xuniq commented Feb 29, 2024

Epic: #4002
Product: Tarantool DB
Repository:

SME: @ a1div0 @ Galiev-Ruslan

Details

Structure template

  • Руководство для начинающих
  • Установка и обновление
  • Руководство пользователя
  • Руководство администратора
    • Руководство по решению проблем
  • Справочник
  • Примечания к версиям

Suggested structure

The new structure is described in the doc:

https://docs.google.com/document/d/1t0s0CWA6iEyzbvr7dbQlgFqfg1_yjja5JTOd7TF2EHw/edit

Definition of done

In scope of this issue:

  • Check the current structure in the docs
  • Create a new structure with the existing content based on the template
  • Validate it with @ a1div0 @ Galiev-Ruslan
  • Restructure the existing docs according to the new plan
  • Add sphinx config files and test a local doc build

Note that the docs will not be proofread in scope of this issue. This will be done later.

Локальная сборка

Какие остались проблемы и вопросы:

  1. В toctree нельзя напрямую добавить файл, который находится за пределами doc-проекта (например, README в корне репозитория). Есть workaround для myst, где в toctree добавляется .md с include, но вместо инклюда видна только пустая страница:
    https://myst-parser.readthedocs.io/en/v0.16.0/sphinx/use.html#include-a-file-from-outside-the-docs-folder-like-readme-md

Сейчас в структуре несколько md-файлов, которые находятся за пределами doc (README в корне репозитория и содержимое ../client/utils/.md). Нужно либо найти обходной путь, чтобы добавить в токтри эти файлы или как-то копировать контент?

  1. Во всех md-файлах с toctree использована директива myst {toctree}. Единственный файл, где не получилось так собрать toctree - в главном index.md. Собрать его получается, только используя в файле rst-обертку для токтри, директива {toctree} из myst у меня не тут не сработала. Пример обертки:
..  toctree::
    :caption: Содержание:
    :maxdepth: 2
    
    overview
    getting_started
    install_and_upgrade
    user_guide
    admin_guide
    reference
    releases
  1. В структуре осталось несколько файлов, которые еще не добавлены ни в какой toctree + остались старые ссылки/якоря, которые будет постепенно обновлены.
@xuniq xuniq added restructure Related to the transfer of sections, text. TDB labels Feb 29, 2024
@xuniq xuniq self-assigned this Feb 29, 2024
@xuniq xuniq closed this as completed Apr 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
restructure Related to the transfer of sections, text. TDB
Projects
None yet
Development

No branches or pull requests

1 participant