Suggested template/folder structure to docs

[NanezX]

Hi everyone, hope you're well.

Our team want to suggest a structure to the documentation generated by the tool. This would be awesome to us and improve how we can use and share that documentation.

Currently I have an idea around how can be the template. Since we have a lot of entities, and some of them go by "groups", we would like to have a structure where a folder contain all the doc related to X types of entities. Something like this (I will use our entities as example):

docs/—
      |
      verify/-
      |      |
      |      VerifyFactory.md
      |      |
      |      Verify.md
      |      |
      |      (each entity related to verifies)
      |
      sale/--
      |     |
      |     SaleFactory.md
      |     |
      |     Sale.md
      |     |
      |     SaleStart.md
      |     |
      |     (each entity related to sales)
      |     
      gatedNFT/--
      |         |
      |         GatedNFTFactory.md
      |         |
      |         GatedNFT.md
      |         |
      |         (each entity related to gatedNFTs)
      |
      ...

The way that I think this could be done is clasifying the entity in a desired type with a tag or identifier together with a description per entity. Something like one of these:

# EmissionERC20
# <DESCRIPTION>
type EmissionsERC20Factory @entity {}

# @EmissionERC20
# <DESCRIPTION>
type EmissionsERC20Factory @entity {}

# @type EmissionERC20
# @description <DESCRIPTION>
type EmissionsERC20Factory @entity {}

With this, the "type" will be use as folder name, and inside will be added all the doc of the entity that have that type. If two entities have the same type, then both md files will be added in that folder.

Hopefully make senses all :) Let me know what do you think around this.

[pelletier197]

This seems to make sense to me. I have a few questions for you

1. Would you like to have this in the existing carbon template, or a new markdown template? At the moment, markdown output is not supported, but this is something that would be possible with a little bit of work.

2. Although I agree that would make sense to group like this, do you feel like it would also make sense to keep a grouping by object type? I feel like having everything on one level could be confusing.

docs/—
      |
      verify/-
      |      |
      |      Queries
      |      |           Verify.md     
      |      Types
      |      |           VerifyFactory.md

And so on.

3. What should happen if you don't put a type on one of the documented entity? Fallback into the default folders (queries, mutations, types), raise an error, ignore, etc?

That's a lot of questions, but I want to know more about what you need since this is a quite large request. Thanks a lot!

[NanezX]

Awesome.

1. I understand what you said, but the markdown output would be exactly what we need :)

2. Yes, make senses group by object type. We mostly want to have more detailed information to the documentationabout the entitiy that we have. Something like the doc that we defined above of the entity and be able to handle how they will be grouped in folders. Am I right with this? Is it what you suggest?

docs/—
      |
      verify/-
      |      |
      |      Entities
      |      |           Verify.md
      |      |           VerifyFactory.md
      |      |           VerifyEvent.md
      |      |
      |      Queries
      |      |           Query1.md
      |      |           Query2.md  
      |      Types
      |      |           Int.md
      |      |           BigInt.md
      |      |           Bytes.md

3. I forgot to add that scenario. I though in a fallback which create a "default" folder where if no type is added, the info will be here. Also, if you agree, we can assume if no type is added to the entity - then we can handle that entity as generic and will be to default folder.

We are doing a big project, and we have a really big subgraph. We are working to make a good documentaiton around it. I can link you to our schemas and endpoints, so you can have a better idea :)

Thank you :)

[pelletier197]

If you have a Public endpoint I can watch, I could make my mind around it. I understand what you want. I can try to implement that in the coming weeks, but if you are interested to help, it could be a good first contribution. Since this is almost completely new, it's really free of design. Although I think it's important to try to keep a generic approach that could fit for many different use-cases

[NanezX]

I agree with you that it's iomportant keep it generic. Right now I'm little bussy with our work implementation, but of course I would like to make a contribution here. I can fork and see how all work, but where I can start? In docs or plugins folders?

• This is our latest endpoint: Subgraph API endpoint
• And these are our schemas: Subgraph schemas

[pelletier197]

Thanks for sharing the endpoints. I'll have a look when I get time.

I haven't had time to create a contribution guide just yet. Basically, the project has the following structure

• docs - This is Magidoc's documentation website project. Won't need to touch that for now.
• cli - Magidoc command line that basically downloads starter projects zips and run npm commands on them (npm install, npm build). See here for more info about that. Most likely won't need to touch that either.
• plugins - A bunch of different plugins used inside Magidoc starters: some to generate queries, some to facilitate working with graphql schema with rollup/vite, some to use with Svelte. Each of these plugins are documented in the documentation above. See the plugins folder.
• starters - These are starters to generate documentation websites. They receive the different configuration they need as environment variables (passed by the cli) . The different environment variables are listed in the starter variables project

So to do what you want, you would need to create a new starter in the starters folder (named markdown for instance). The only starter implemented at the moment is made with Svelte and will output html/css/js (carbon-multi-page). If you want pure Markdown, we will need to create something from scratch that would generate a markdown folder structure from a _schema.json.

All this may be a bit over-whelming to start with. I will try to setup a contributing guide next week and I can create an empty shell project when I get time where you could start to work when you get some time 🙂. But I could get on this feature in the coming weeks. I have a few essential features I need to complete in the existing starter before working on another one.