Create TypeScript model for USFM Data API

[GlennPruitt]

As a funder I want to have a description of all APIs in the BT space. Specifically, I want a model of the API for Project USFM Data that will be exposed by Platform.Bible to extension developers. This model must be written in an easy-to-read format (previously GraphQL).

Create documentation for the API for Project USFM Data. Use a standardized way to describe the schema.

Talk to Michael Marshall if you have any questions.

[tjcouch-sil]

Some thoughts from research last year https://docs.google.com/document/d/1nzLREjhttuJ_T4-kcB3RZj-oM4pDCk32D2oMkBcQTLY/edit#heading=h.p75h6tjv7vq9

[irahopkinson]

Asked ChatGPT: "can you use graphql to document an api?"

Yes, GraphQL can be used to document an API effectively. While GraphQL itself is a query language for your API and doesn't provide automatic documentation like some RESTful APIs might have with tools like Swagger, you can create comprehensive documentation for a GraphQL API using various approaches and tools. Here's how you can document a GraphQL API:

1. GraphQL SDL (Schema Definition Language): GraphQL APIs are typically defined using SDL. This SDL can serve as the foundation for your API documentation. You can include comments and descriptions in your SDL to provide information about each type, field, and query.

   type User {
    id: ID!
    name: String
    email: String
    # Additional information about the 'posts' field
    posts: [Post]
   }
   
   type Query {
    # Retrieves a user by their ID.
    user(id: ID!): User
   }

2. GraphQL Documentation Tools:

   • GraphQL Playground/GraphiQL: These development tools often include a section for documentation. You can add descriptions to your types, fields, and queries in the SDL, and these descriptions will be visible in the documentation generated by the tool.

   • Apollo Server: If you are using Apollo Server to implement your GraphQL API, it provides automatic documentation generation. You can use the @description directive to add descriptions to your types and fields.

   const typeDefs = gql`
    """
    Represents a user in the system.
    """
    type User {
      id: ID!
      name: String
      email: String
    }
   
    type Query {
      """
      Retrieve a user by their ID.
      """
      user(id: ID!): User
    }
   `;

3. Third-Party Documentation Tools:

   • GraphiQL IDE: You can integrate GraphiQL IDE into your API, which not only provides an interactive GraphQL query interface but also generates documentation based on your schema.

   • Apollo Studio: Apollo Studio offers a suite of tools for GraphQL development, including a way to document and visualize your GraphQL schema. It can also track usage and provide insights into your API's performance.

4. Custom Documentation: If you prefer more control over the documentation, you can create custom documentation using Markdown, HTML, or any other format. You can use tools like Docusaurus, Gatsby, or even a simple README file to write detailed documentation for your API, including examples of queries and mutations.

Remember that effective API documentation should not only describe the types and queries available but also provide usage examples and best practices. Good documentation helps developers understand and use your API more easily and effectively.

[tjcouch-sil]

Raw USFM - not really used that much Tokens - probably used more. ScrText.Parser. Content of things without extraneous info like verse nums and crossrefs and such. Used for showing in BTerms views

[tjcouch-sil]

*I accidentally put this comment right here. Moved*

[FoolRunning]

@tjcouch-sil, Did you mean to put that in #479?

[tjcouch-sil]

Yep, oops. Sorry. Moving

[tjcouch-sil]

Reopening because Glenn would like to see proposed serialized token format endpoints.

John Wickberg mentioned there is an official USFM parser in the works in Python. It is not production-level code. I reached out to Martin Hosken regarding serialized token format outputs from this parser to see if we could consider using that.

Other options are using the Slate-inspired JSON format I created for the POC last year. We could also try Sofria.

[tjcouch-sil]

USJ info!!!

tcdocs/grammar/usj.js at usj · usfm-bible/tcdocs - JSON Schema Proposal for JSON representing USFM/USX Contents · usfm-bible/tcdocs · Discussion #42 - Proposal and discussion for USJ Examples: tcdocs/tests/usfmjsTests/inline_God/origin-usj.json at usj · usfm-bible/tcdocs nice-usfm-json/samples/character/proposed.json at main · mvh-solutions/nice-usfm-json nice-usfm-json/samples/character/origin.xml at main · mvh-solutions/nice-usfm-json

[tjcouch-sil]

Found some links for various dts build tools that could help us to auto-generate these reader-friendly types more easily https://www.reddit.com/r/typescript/comments/gquyk2/convert_dts_tree_as_a_single_dts_file/

[tjcouch-sil]

Relied on IProject and USJ schema to create the types.

First draft: ParatextStandardProjectDataProviderExpanded

Notes for ease of reading:

• A "selector" is an object that a data provider receives that informs what subset of all its data is being interacted with. For example, a VerseRef could be a selector to tell a Scripture-related data provider what verse to get data for
• See TypeScript's function documentation for information regarding callback function type syntax and how to read it
• Quick reference to a couple of types from papi.d.ts that are used in the above types:
  • DataProviderSubscriberOptions
  • DataProviderUpdateInstructions

[tjcouch-sil]

Added in #538

[tjcouch-sil]

Need to add USX endpoints

[tjcouch-sil]

Found an interesting library that analyzes typescript and creates graphql types for your queries. Maybe we could use this one day if we ever made a graphql system in P.B https://gql-tada.0no.co/