Comments (5)
This seems to make sense to me. I have a few questions for you
-
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.
-
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.
- 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!
from magidoc.
Awesome.
-
I understand what you said, but the markdown output would be exactly what we need :)
-
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
- 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 :)
from magidoc.
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
from magidoc.
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
from magidoc.
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.
from magidoc.
Related Issues (20)
- Host on Azure storage account static website HOT 6
- Document how to generate documentation for multiple GraphQL URLs HOT 4
- Argument descriptions are not formatting common mark. HOT 2
- Sort arguments as default - Not alphabetically HOT 6
- pnpm required as of 3.4.0 HOT 2
- Ruby Syntax Highlighting from Prism not being applied HOT 6
- Example body has a fixed max-height, meaning queries with a lot of possible fields are hard to easily parse visually HOT 2
- Optimizations for "multi-site" use case HOT 2
- Overriding template CSS with custom styles HOT 4
- Always prepend directive names with `@` HOT 1
- logo with siteRoot not working HOT 2
- generate hangs on "Build Template" and never Completes HOT 8
- Enum description doesn't support markdown HOT 4
- Add option to remove deprecated fields from documentation HOT 2
- Query generator for unknown values HOT 4
- Support download links HOT 4
- Blacklisting HOT 2
- Alternative documentation layout HOT 4
- Large scale GraphQL APIs HOT 3
- preview command with --host option HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from magidoc.