search

nspcc-dev / doc-fs-neo-org

NeoFS Documentaion site
Other
0 stars 0 forks source link

Evaluate neofs-spec reuse possibility #35

Open roman-khimov opened 1 year ago

roman-khimov commented 1 year ago

See https://github.com/nspcc-dev/neofs-spec/, it has quite some content there, but I'm not sure how easy it is to reuse it for the doc.fs.neo.org. It uses very specific tooling, it has a structure of its own. We need to evaluate this possibility, can this be done, how can this be done, what changes are needed (if any) to make it possible.

mike-petrov commented 1 year ago

A big plus is that we have the underlying markdown on both github and docsite. All the components look good: tables, code, headers, formatting. Transferring to the docsite shouldn't be a problem, but there are a couple of things here:

  1. Each .md file must have the necessary parameters at the beginning, according to the following structure: 
    ---
title: "API & SDK"
description: "API and SDK implementations"
date: "2023-01-13"
---
  2. Structure of the neofs-spec repository does not allow for good navigation by section. In the case of moving current structure there will be a lot of tabs on one page, which I think it is better to separate.
image
  1. Relative paths for images are constructed in different ways: pic/acl-basic-private.svg (github), ../pic/acl-basic-private.svg (docsite)
mike-petrov commented 1 year ago

There is an idea how to solve the second point without changing the repository structure. Display sections in dropdown form and the ability to switch to any topic (like Nodes section).

image
roman-khimov commented 1 year ago

Can we include an MD from MD? We may have some "wrapper" MDs here that include ones from neofs-spec this way (with neofs-spec residing in some submodule). This will likely solve the second issue as well.