dwhieb / jschemer

A Node.js library to generate documentation for JSON Schemas

Hello, I'm Danny! 👋🏻 I am a linguist. 🗣

I work with the Chitimacha Tribe of Louisiana to help them revitalize their once-dormant language. We are using archival materials to produce a modern dictionary and grammar of the language.

I also run the Digital Linguistics (DLx) project, which provides data formats and web-based tools for working with linguistic data. Check out the DLx developers page or the DLx organization on GitHub.

I am a member of the Algonquian Components Project, a National Science Foundation–funded database of morphological components in Algonquian languages, which uses the Digital Linguistics infrastructure.

Digital Linguistics (DLx) Blog

• Scription > DLx v0.11.0
• Scription v0.7.0
• DLx Word Aligner Library
• DLx Styles Library v0.19.0

🌐 Find Me Online!	💻 Digital Linguistics (DLx)
🔗 my website	🔗 website
💬 Twitter	👨🏼‍💻 developers
📚 ResearchGate	GitHub
🎓 Academia.edu	📝 blog
👨🏼‍🏫 Google Scholar	💬 Twitter
👔 LinkedIn
0000-0002-1411-3773

jschemer's Issues

add "key" attribute to Phrase spec

allow for self-referring schemas

Look at Phoneme.allphones for an example

set maximum rule (text width) for docs

rewrite Readme

closed by f099753

better organization of src and out directories

handle $ref URLs both with and without #

setup project workflow

• CONTRIBUTING.md
• PULL_REQUEST_TEMPLATE.md

list of schemas should scroll if too long

add individual (sub)schemas to generated documentation

This is the template for individual schemas (and subschemas).

schema.hbs

support command line

index.js contains the conditional statement which determines which action to take.

If run from the command line, run one file (which depends on the non-command line file).

If run as a module, export the non-command line file directly.

What to name each of these?

Add command line tests as well.

support custom fields

Test with "argumentStructure"
Allow people to choose from common custom fields

some items in "dependencies" key not displaying correctly

"not" key isn't displaying properties

use http rather than https for all references

copy jschemer.css into out folder

• create a branch with a descriptive name about what change you're making (see above)
• write your code! 🎆
• test your code
• commit changes
• sync to github
• make a pull request

inline schema links not working properly

generate index.html

Overview: You'll be writing a function called createIndexPage, which uses the file src/index.hbs as a template, and creates a new file in the out folder called index.html.

Detailed steps are below. Please check off each item once it's done. Don't forget to test your code each step of the way too. If you get stuck or run into trouble on any part, and can't find the answer online, just comment here and I'll reply ASAP.

P.S. As you work through this, spend some time learning more about Atom too. Here's the help documentation for it. Eventually you should read everything in Chapter 2: Using Atom (except for the Version Control section). Keep learning new keyboard shortcuts and using the ones you already know too.

P.P.S. You can click on the links below to take you to the particular sections of code I'm talking about.

P.P.P.S. I created a script that will generate example documentation, so you can use this to test your code. Instead of running jschemer <filename> in node, now you can just run the command npm run example. This will create a folder called example and output the documentation there. So running this command is an easy way to test your code as you go.

Steps to follow:

• Sync the latest changes from GitHub.

• Read the GitHub flow guide.

  • We'll be following these steps as we work together on this code. Reading this will help you know what's coming, and understanding why we're doing each step as we do it.

• Create a new branch called generate-index (because the code you're writing will be generating the index.html page).

  • You'll make all your changes on this branch. When you're done, I'll merge your changes into the master branch. This allows you to make changes without worrying about accidentally breaking code in the master branch.
  • You should sync your changes to this branch frequently as you work. Don't worry if the code isn't working right. That's what branches are for - to mess around with code until you've got it the way you want. Usually, nobody else even looks at your code until it's time to merge your changes into the master branch.

• Look at the code to understand how your createIndexPage function fits into the larger jschemer function.

  • I made a lot of changes to the code, to avoid the "callback hell" problem I told you about. Now, the jschemer function starts by first validating all the arguments and options, then declaring some variables you'll need later (like the path to the CSS file, etc.), then declaring a big list of functions (listed alphabetically in the code) that do different things: copyCSS, createIndexPage (the one you're writing), getFileNames, etc. Then, towards the end of the jschemer function, all those smaller functions get run in their proper order. So your createIndexPage function is one of the last steps in the process.
  • I've already created an empty createIndexPage function for you. You'll be writing your code inside that, following the steps below.

• Use the fs module to read the contents of src/index.hbs.

  • index.hbs contains the template you'll be using in the next step.

• Compile the template using Handlebars, and save the resulting function to a variable called convert.

Next, you need to tell your convert function what data to use when it converts the template to HTML. In your learning folder, you did this by reading the file called data.json, and passing its contents to convert. This time, instead of reading the data from a file, you're just going to create the data object yourself, and it'll be called context this time instead of data.

• Create an object called context with 3 properties:

  1. css - Set this equal to the cssPath variable (see here)
  2. nav - Set this equal to the nav variable (see here)
  3. readme - Set this equal to the readme variable, which is passed to your function as an argument (see here)

• Call the convert function on your context object and save the result to a variable called html.

• Create a file called index.html in the out folder with html as its contents.

• Update your generate-index branch with the latest changes from the master branch, then sync your code.

• Open a pull request to merge your changes into the master branch.

• Celebrate with your drink of choice 🍷 🍺 🍻 🍸 🍹

Once you've made the pull request, I'll see it and review your code. I'll ask you to make various revisions, then we'll merge your code into the master branch.

create test schema

Go through the entire JSON Schema Draft 07 spec, and create a schema that will test each part of the specification.

add shields to readme

rename lexiconRef to lexemeReference

add styling for <em> tags in descriptions

descriptions not displaying inside $refs

e.g. description inside allomorph.transcriptions

add pages for each schema to generated documentation

This is the template for individual schema pages (top-level schemas).

page.hbs

use marky-markdown to support GitHub-flavored markdown

https://www.npmjs.com/package/marky-markdown

allow HTML in source with "html" option

Perhaps allow this (and other markdown-it options) to be set by the user. These options are then passed to markdown-it during initialization.

issue with `allOf`

The following doesn't render as expected:

    "allOf": [

      { "$ref": "http://cdn.digitallinguistics.io/schemas/Language.json" }
    ]

support rendering examples (if not already supported)

support both callback and promise

https://blog.risingstack.com/how-to-become-a-better-node-js-developer-in-2016/?utm_source=nodeweekly&utm_medium=email

update digitallinguistics.org > digitallinguistics.io

support Draft 07

setup Node version manager

You should run all testing on Node v10.x

"title" missing for definitions items

Location.geoJSON $ref link not linking correctly

Make sure $ref links are being parsed correctly

Fix links in readme badges

add styling to landing page

• Use LESS, and store the LESS file alongside its Handlebars template (create folders for each template, and adjust scripts as needed).

• The LESS files should compile into a single CSS file for the landing page (a separate, single CSS file will be generated for the schema pages).

• The CSS file for the landing page should include the CSS for the readme.

setup automated deployment to npm

setup Travis

add Fira Sans font

highlight subschemas on hover

index.hbs

This is the main landing page for the generated documentation.

make schemas collapsible

setup Babel

This may not be necessary.

You might need to setup webpack to coordinate Babel and TypeScript.

Update main and bin fields in package.json to use /dist folder.

schemas list not sorting consistently

create README.md

add buttons to expand/collapse all schemas

do not set background color

It's not accessible to force the user to view it with a white background

add base filepath config option

This would allow someone to provide a base filepath, against which relative paths in $ref keywords could be defined. jschemer.js would then need to synchronously read the file at that location, and Object.assign the properties from the local definition onto the external definition, then update the local definition with the external one.

setup labels

add example folder

links to inline definitions are incorrect