Giters

Open-Cap-Table-Coalition / Open-Cap-Format-OCF

Open Cap Format (OCF) - The Open Source Company Capitalization Data Standard. OCF can be used to structure and track the complex data structures necessary to build and maintain accurate capitalization (cap) tables.

Home Page:https://opencaptablecoalition.com

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

[Bug]: The TaxId has a dead link

xudiera opened this issue · comments

commented

Current Behavior:

  1. Navigate to link: https://open-cap-table-coalition.github.io/Open-Cap-Format-OCF/schema_markdown/schema/types/TaxID/
  2. Click the country link, observe that it redirects to a 404 page

Expected Behavior:

Expect link to navigate to: https://open-cap-table-coalition.github.io/Open-Cap-Format-OCF/schema_markdown/schema/types/CountryCode/

commented

TWG Notes

  • there might be a few of these, our path conversions are in play
commented

Hi Folks, i created a little web crawler to try and find these dead links. I found a few cases, that I will document here:

  • Case 1: (medium priority) Pretty much all types files have broken links. I tried looking at the schemaWriter, and it's a little hard for me to wrap my head around without doing a deeper dive. All the other schema documentation types (enums, files, primitives, objects) work correctly.
  • Case 2: (low priority) a couple dead links in our explainers / supplementary information:
  • Case 3: (very low priority)edit_uri (mkdocs config) needs to be updated. The pencil icon on any mkdocs page is supposed to link back to the github page and allow the user to edit inline. The default links back to a github url with the branch name master, but our branch is called main. I implemented a fix that works successfully on my own repo, I can recreate this pr #384 and this will solve most of the broken links

This list is not exhaustive, but I think ensures our site has mostly working.

commented

How to reproduce broken types:

  1. Navigate to any schema type file (example)
  2. Click a link in the properties table, such as Phone, Name
  3. Observe that the url does not follow the relative path, but tries to link to the root of the docs site.

Expected Behavior: It should link in the same directory, but a different file.

commented

Ok implemented a fix for this. Here's what is going on.

How Doc Generation Works:

  • Our Schema generator tool will read input json, and figure out the references between different schema files by deconstructing the $ref json property. It builds a semantic representation to generate the markdown, creating PropertyNodes which construct the markdownTable used in every documentation file (corresponding to the "properties" section of each markdown file).
  • MkDocs is a tool that will take an input markdown file, and generate a stylized HTML / CSS representation as an output. However, because MkDocs does not support absolute paths, markdown files need to link to each other only via relative paths. @JSv4 wrote a handful of utilities for markdown files to be able to construct relative paths to link to each other, allowing us to have our github and our documentation site able to follow references correctly (See PR #326). This works fine for almost all cases, except for Types.

The issue:

  • Types, coincidentally, are the only instance of our json schema files where the the schemaNodes and propertyNodes are in the same folder. The above method tries to compute the relative path differences between these files, and would return "" for files where the properties and the schema were in the same folder.
  • As a result, the links that would be generated would point to the root directory.

The fix:

  • In cases where the source path and target path are in the same repo, instead of returning "", return "." so the path construction assumes relative linking.
commented

Thanks @naveedn. That was a big lift. Will review.

commented

Closed by #385