Only url introspection is defined in the doc. The 'file' and 'raw' ones should be included as well.

Thank you for this great generator.

While Build Template it throws this error:

 Error: Cannot generate a random value for scalar 'smallint'.
  The random generator is not able to randomly generate a value for non-standard GraphQL scalars.
  You have to provide a custom factory by providing this in your config:
  {
  'smallint': () => generateRandomCustomScalar()
  }

Can you please provide an example on how to fix this? Documentation is not clear enough, where the 'smallint': () => generateRandomCustomScalar() should go in the config? Can you provide an example of generateRandomCustomScalar()?

Dependabot actions may be configured for automatic dependency update with pull requests. These dependency checks may run every day and fixes may be merged automatically if they are non-breaking.

https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions

For now, a few pieces of the NodeJS projects are tested, but there is still missing a lot of coverage in many of them. Mainly, the CLI lacks of tests and that would require them the most.

• Tests for the configuration parsing / error handling
• Tests for each task of each command
• Potentially, more integrated tests for the command line runner, but these would be harder to write.
• Potentially, tests for the CLI and arg parsing.

Describe the problem

Currently, magidoc beautifully displays the descriptions that are present in our GraphQL schema. Our schema makes extensive use of GraphQL interfaces. That is, we'll define an interface in a common place, and then define concrete types in one or more other model files. As you know, when a type implements an interface, all the field names in the interface must be specified in the type. Because of this, if we add descriptions to the fields in an interface, it would be nice if those descriptions would propagate to the concrete types that implement the interface, presuming the concrete type hasn't already added a description for the field. This way, we only have to provide a description once, and it will automatically get replicated to the places it applies.

Describe the proposed solution

Either makes this built-in behavior, or provide an option in the mjs config file to control if descriptions are propagated from interfaces to other interfaces or types that implement the interface, if that implementing interface/type doesn't provide its own.

interface MyInterface {
   """ Interface-provided description of field1 """
   field1: String!

   """ Interface-provided description of field2 """
   field2: String!
}

interface MyType implements MyInterface {
   field1: String!

   """ Type-provided description of field2 """
   field2: String!
}

Given the above schema, when magidoc processes the schema, it would recognize that MyType:field1 does not have a description, so it propagates the description from MyInterface:field1 to MyType:field1. Also, magidoc would recognize that MyType:field2 has provided a description, so magidoc would not copy the description from the MyInterface:field2.

Alternatives considered

It's possible this functionality could be implemented in a graphql codegen plugin (such as in the schema-ast or introspection plugin). But, if someone isn't using a codegen plugin, but rather doing a live introspection query, they could not benefit from this behavior.

Importance

would make my life easier

Additional Information

There are many benefits to this functionality. First, for users of the static doc, they will see descriptions all the way from interfaces to the concrete types. For us developers, we only have to write our descriptions once, and get all the benefits of not copy/pasting descriptions from interfaces from concrete implementations.

Considering the carbon template is built with vite, it should be feasible to create a dev mode where we listen to the magidoc.mjs and any file referenced inside it. We could re-copy the required assets on change and update the environment variables populated by an .env file.

Step 1 - Exploration

Make sure ViteJS reloads the dev template when changing the .env file. If this does not work, this feature is going to be harder to implement.

Step 2 - Change the cli to use .env file

Right now, env variables are passed directly by process, which would not work well with dev server. If we do this change for dev, may as well do it for build as well and have one way to do this.

Step 3 - implement the dev/watch cli command

This command needs to listen to every change in the magidoc.mis file or any file referenced in it. When something changes, it should copy back the changed / removed assets in the template, change the env variables, etc.

Ideally, deleting assets should reflect in the template as well. Should Templates define a list of default assets?

Need to add the queryGenerationFactories to the docs.

https://magidoc-org.github.io/magidoc/templates/carbon-multi-page#supported-options

After upgrading to 2.1.0 it throws this error:

✔ Determine tmp directories [0.0s]
✔ Select Package Manager [0.1s]
  › Selected pnpm
↓ Template already unzipped. [SKIPPED]
↓ Template already unzipped [SKIPPED]
✔ Install dependencies [0.6s]
✔ Resolving template configuration [0.0s]
  › Found 7 supported keys
    Target schema location: ./src/_schema.json
✔ Load GraphQL Schema [0.7s]
✔ Write variables file [0.0s]
✔ Build template [1s]
✖ Move output

------- Stacktrace -------
[Error: ENOENT: no such file or directory, lstat '/var/folders/yz/dk5dbx8n2hqcfk1kdktxmknh0000gn/T/[email protected]/build'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'lstat',
  path: '/var/folders/yz/dk5dbx8n2hqcfk1kdktxmknh0000gn/T/[email protected]/build'
}

I'm using node 14.9, latest pnpm and lib version 2.1.0.

It seems that Build Template step took 1s to finish while on v2.0.0 it took like a minute to finish.

edit: I totally removed the website.options.queryGenerationFactories, runned magidoc generate and it didn't throw an error about missing scalars, it went directly to the error described above since the scalars check is happening during Build template step.

edit 2: I've manually created the build folder, runned magidoc generate, (the process was unexpectedly really fast), runned magidoc preview, visited localhost:4000 and the page was blank (as expected since the Build template step took only 1 sec to finish).

edit 3: don't know if it matters but my global packages are installed in $HOME/.npm-global folder instead of npm default one so I won't have to use sudo while installing global packages.

Ideally, users should be able to customize the top header with any icon they want and with any link they want. For Magidoc, this is required to put the Github repository link in the top-bar.

This may be difficult to do using carbon-icons, but maybe there is a way.

See this comment for more details. The handling of recursive input fields is done in a way that we throw as soon as we traverse a field that is non-nullable two times, which doesn't work well when recursion is made through multiple objects.

{
  Object1! { # non-null
    Object2 { # nullable
      Object1! {  # non-null
        Object2 # nullable
      }
    }
  }
}

Right now, this schema will throw an exception of invalid recursion in the model. This should generate something like

{
  Object1 { 
    Object2 {
      Object1 {
        Object2: null
      }
    }
  }
}

Along with that, the error message in that exception should be improved to provide more details about what happened.

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.

Tables when using markdown are responsive, until the number of columns grows too much. At some point, the table just ends up overflowing the page.

The same thing can be seen when using inline code inside the tables.

The href on the logo of the generated website doesn't return to the main page: https://magidoc-carbon-multi-page.netlify.app/welcome

Describe the problem

At the moment, starting a dev server while there is already one running relies on vitejs --strictPort argument to crash if the port is already in used, which is not ideal, as it relies on vite's implementation.

Describe the proposed solution

We should ideally not start the dev server at all if a port is already used, and crash with a significant error.

Alternatives considered

Check out the series of propositions here:
https://stackoverflow.com/questions/19129570/how-can-i-check-if-port-is-busy-in-nodejs

Importance

nice to have

Additional Information

No response

Right now, the meta tags of the website are not modifiable. They are all empty.

• favicon
• description
• author
• keywords
• etc

These tags are super important for a good SEO. Meta tags are simple key-value properties. I think it's not necessary to validate the key and the values, simply using a dictionary or a list should be good enough to let the users do what they want.

https://gist.github.com/whitingx/3840905

Describe the problem

Currently, when we see a GraphQL type in the API, there is not really any easy way to know at a glance which query can fetch that field. This is more problematic for nested fields, because the only way to know how to query it is to backtrack into the references.

Describe the proposed solution

We should have a new section Queries that indicates how this field can be used/accessed from a root query type.

Alternatives considered

No response

Importance

would make my life easier

Additional Information

No response

Describe the bug

I'm trying to use the following configuration in my magidoc.mjs config file:

export default { 
   introspection: {
      type: 'sdl',
      paths: ['./src/generated/schema.graphql'],
   },
   // other fields omitted
}

The file ./src/generated/schema.graphql exists and contains our entire gql schema.

When I run the generate command, it fails with the following stack trace:

------- Stacktrace -------
Error: No paths found matching target glob patterns: [C:\GitProjectRepos\shure.system-api\sprint-q3.4-gqldoc\packages\standalone-server\src\generated\schema.graphql].
If you used relative paths, make sure the paths are relative to where the node command was launched or use absolute paths.
    at readFullSchema (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/rollup-plugin-parse-gql-schema/build/schema/parse.js:20:15)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async parseGraphqlSchema (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/rollup-plugin-parse-gql-schema/build/schema/parse.js:6:23) 
    at async parseSchema (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/rollup-plugin-parse-gql-schema/build/index.js:5:20)
    at async Object.executor (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/cli/build/tasks/all/loadGraphqlSchema.js:20:21)
    at async Task.run (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/listr2/dist/index.js:960:11)
    at async C:\GitProjectRepos\shure.system-api\sprint-q3.4-gqldoc\node_modules\p-map\index.js:57:22

I know the path is correct, and it is relative to where I'm invoking the generate command. If I use the file option using the same relative path, as listed below, generate works.

export default { 
   introspection: { 
      // this works.
      type: 'file',
      location: './src/generated/introspection.json',
   },
}

I wanted to use the schema file instead of the introspection file with the hope that the comments we've included in our schema file will show up as useful comments in the generated document.

Reproduction

you can use the information above

Logs

Error: No paths found matching target glob patterns: [C:\GitProjectRepos\shure.system-api\sprint-q3.4-gqldoc\packages\standalone-server\src\generated\schema.graphql].
If you used relative paths, make sure the paths are relative to where the node command was launched or use absolute paths.
    at readFullSchema (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/rollup-plugin-parse-gql-schema/build/schema/parse.js:20:15)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async parseGraphqlSchema (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/rollup-plugin-parse-gql-schema/build/schema/parse.js:6:23) 
    at async parseSchema (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/rollup-plugin-parse-gql-schema/build/index.js:5:20)
    at async Object.executor (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/@magidoc/cli/build/tasks/all/loadGraphqlSchema.js:20:21)
    at async Task.run (file:///C:/GitProjectRepos/shure.system-api/sprint-q3.4-gqldoc/node_modules/listr2/dist/index.js:960:11)
    at async C:\GitProjectRepos\shure.system-api\sprint-q3.4-gqldoc\node_modules\p-map\index.js:57:22

System Info

$ npx envinfo --system --binaries --browsers --npmPackages "{@magidoc/*}"
npm WARN config global `--global`, `--local` are deprecated. Use `--location=global` instead.

  System:
    OS: Windows 10 10.0.19042
    CPU: (12) x64 Intel(R) Core(TM) i7-10850H CPU @ 2.70GHz
    Memory: 4.99 GB / 31.73 GB
  Binaries:
    Node: 16.16.0 - C:\Program Files\nodejs\node.EXE
    Yarn: 3.2.0 - C:\Program Files (x86)\Yarn\bin\yarn.CMD
    npm: 8.11.0 - C:\Program Files\nodejs\npm.CMD
  Browsers:
    Chrome: 103.0.5060.134
    Edge: Spartan (44.19041.1266.0), Chromium (104.0.1293.47)

Severity

serious, but I can work around it

Additional Information

No response

The UI templates and component libraries lack of unit test. The only tests they get are build and type-checking, which is not enough to ensure they don't break.

Explore testing solutions for Svelte components. Ideally, make these large tests instead of unit tests, so that they don't break for no reason. Only unit test the logic.

Following the basic steps from the Getting Started section of the docs errors with the following message on Windows when trying to run generate:

> npx @magidoc/cli@latest generate
Only URLs with a scheme in: file, data are supported by the default ESM loader. On Windows, absolute paths must be valid file:// URLs. Received protocol 'c:'

My "magidoc.mjs" file:

export default {
  introspection: {
    type: "url",
    url: "https://graphiql-test.netlify.app/.netlify/functions/schema-demo",
  },
  website: {
    template: "carbon-multi-page",
  },
};

Support for meta customisation was added in #51, but favicon is a different property than meta. It would need to be added separately.

Add documentation for static assets feature.

Right now, there is no way to modify the left menu and the page content. This should be added in the possible options.

The project should offer contributing guidelines

• PR template
• How to setup to develop locally
  • tools required
• etc

Describe the problem

Need more details about gfm, tables, html, etc.

Describe the proposed solution

Add more docs

Alternatives considered

No response

Importance

nice to have

Additional Information

No response

Haven't figured out why this happened. May be due to the npm version, or a conflict in a library. This seems to happen when using yarn as well, so chances are that some library does not define its dependencies properly for yarn/npm.

Set up issue templates for opening feature requests and bug requests. Questions asked should be

Bugs

• Magidoc version used
• System info
• component (which template, cli command or plugin is in issue)
• explain the problem, with screenshots and as most details as possible
• If possible, the magidoc config used.

Feature

• what feature is wished and why? give as much details as possible. What are the proposed ways to implement this?
• screenshots/mockups/examples

Markdown bullet lists should handle starting from another number than 1.

Use start attribute on ol elements, along with the start property passed by marked.

We must find a way to show the directives applied to a given field, since some directives may contain useful information, like validations and permissions.

The query generator throws an exception very specific to the generator. The template should catch this exception and re-throw a more specific one.

See this comment for more details

Right now, query generator uses the fake generator to create responses, but the response may not match the request generated because it is generated by the input parameter algorithm.

Responses should be generated using the same algorithm as queries and using a response builder.

Implement reverse schema mapping. For now, GraphQL.js offers a uni-directional mapping, so you can get the types and their fields.

Implementing a reverse mapping allows to find where a field is used, so we can easily query the model in two ways.

Example of questions we want to answer

• Where is a type used (an input type, a scalar, etc)
  • So that when you get on the page of a Type, you can see its usage.
• What types implement an interface?
  • So that when you visit an interface page, you can see the implementing types.
• etc?

Requirements

• speed
• simple interface to interact with
• ideally, something where you pass the graphql model, and it returns you a reverse mapping of it

• Node 16+
• pnpm (recommended 7+), yarn or node
• other?

The query example should contain a section that shows an example of response. This should be easy to add in the query generator module. The code should be relatively similar to what generates input objects. It may require some generalization.

Issue #67 revealed an issue with Windows that was not revealed by current unit tests on Linux, and we're interestingly not revealed by unit tests even when running them on windows.

However, the issue was found when running a generate command using the cli. So I see 3 things that could be done:

• add unit tests for windows in the GitHub actions (and ideally for node 17 as well: right now we test only 16). Make sure the shell used is PowerShell and not bash.
• find a way that jest can run the tests using node version 16. For some reasons, parts covered by the tests were not failing on windows and they should have. (Reader.spec.ts)
• run a generate command as a unit test in the pipeline (and maybe do some asserts). This could be considered an integration test of the cli. This one would have failed on windows if it existed.

Add documentation for all the supported markdown features in carbon template.

• tags
• notifications
• lists
• etc

We should use a logger for the CLI project rather than calling console.log directly, and an ESLint rule should be added to forbid using console.log, as they are often forgotten during testing.

Each project already exports coverage file in the CI when running the test-ci script of the root project. The objective is to

1. Have access to coverage reports, using any tool wished.
2. Add the ability to fail the branch pipelines if the coverage drops compared to the master branch.

Suggestion of tool

• https://app.codecov.io/gh free for open source projects

Magidoc needs an ability to provide static assets that can be referenced directly in the markdown. This includes images, .nojekyll, videos, etc.

The idea is to provide a configuration for custom assets paths, that would be added to the assets of the built website and can be referenced directly then.

Given you have a folder ./assets that contains logo.png, you could do:

export default {
  website: {
    extraAssets: ['./assets'],
    options: {
     appLogo: "/logo.png",
   }
  }
}

This would allow you to override the favicon as well for instance, provide a .nojekyll file, or a custom robot.txt. Ideally, folder structure should be conserved for assets.

Update documentation with SDL introspection and Rollup-parse-graphql-schema. See #40

Missing the new feature pages inside the documentation for Magidoc Configuration

Right now, only the introspection query or using an introspection result directly on the computer are supported. Is would be required to add support for SDL to generate the introspection result.

Requirements

1. Allow glob syntax to select multiple SDL files
2. Make a rollup plugin like the one for introspection that can be used both by the CLI and by the docs project directly.

Describe the problem

I want to display multiple content in a tab container but there is no way to do so in the markdown format supported.

Describe the proposed solution

Implementation of a tabs component in markdown using containers. Example of what it would look like

::: tabs
---Tab1
Some markdown content and so on

---Tab 2 
Some tab 2 **with markdown** inside 👀
:::

Alternatives considered

No response

Importance

would make my life easier

Additional Information

No response

We should add a toggle in the UI to decide on the null generation strategy. For now, never-null is hard-coded.

Right now, it is impossible to provide custom factories in the magidoc options, making the build certain of failing if some custom scalars are used.

When I go to one of the documentation pages, say this: https://magidoc-carbon-multi-page.netlify.app/queries/findListByID, the browser ends up turning the url to lowercase, which probably breaks routing.

I tried this on Chrome, went to a page from the UI, and after I refresh the tab it results in 404.

I did it with "Paste and Go" in Safari and got the same result immediately (it probably lower-cased the url as part of the operation)

I'm using Chrome and Safari in iOS 15.5

For documentation websites that do not start at the root URL path (example, https://my-website.com/docs), the current setup of Magidoc will not work. The base path must be specified to svelte-kit for this. See: https://kit.svelte.dev/docs/configuration#paths

Implementing search capabilities inside the UI would be a really great addition. Ideally, this should be implemented using a lightweight search index that should be pre-compiled and stored in the website's assets for maximum speed.

Requirements

• lightweight
• fast
• scales well for large APIs
• Be re-usable for different templates.
• Allows the templates to customise their own URL templates. The plugin should not take care of the URLs

Tools

• https://github.com/nextapps-de/flexsearch Seems to be the most performant engine. See if project is solid enough.
• http://elasticlunr.com/ Leading implementation before
• https://fusejs.io/

Default Hasura types should be supported by query generation factories by default

    {
        _text: "loremipsum",
        bigint: 1000,
        date: "2022-03-06T08:23:45.000Z",
        float8: 0.1,
        geography: { type: "Point", coordinates: [0, 0] },
        geometry: { type: "Point", coordinates: [0, 0] },
        jsonb: {},
        numeric: 1,
        smallint: 42,
        timestamp: "2022-03-06T08:23:45.000Z",
        timestamptz: "2022-03-06T08:23:45.000Z",
        uuid: "a12ce80c-42e3-4149-89cc-4afda30e5e7f",
      }

See #92 for more details.