docs icon indicating copy to clipboard operation
docs copied to clipboard

Clean up the `dsp` branch

Open jouni opened this issue 1 year ago • 1 comments

The dsp branch has several issues:

  • The "Foundation" section has duplicate pages with almost identical content: Screenshot 2023-05-09 at 9 41 53
  • "Figma Libraries" page is duplicated (one page at the top level, another under "Components").
  • The articles/ds/ folder is unnecessary, now that the script that picks updates from the latest branch can move pages. We should remove the extra ds/ folder.
  • The articles/styling/ folder is not shown on the website at all, since it’s outside the ARTICLES_PATH folder. This breaks the "Styling" card link in the "Components" section index page, and links from the individual component "Styling" sub-pages. I wonder if it’s even beneficial to add this section to new DSP projects.
  • The scripts/dspublisher-init.js file should be removed after the project has been initialized.
  • None of the component pages should be marked as "commercial" (the purple dot after the navigation item is not visible, but the extra class name is there from the section-nav front matter attribute).
  • The dspublisher/docs-theme/header.ts file is deprecated API. It should be dspublisher/docs-theme/init-browser.ts instead. But I’m not sure there’s much benefit in giving users empty files in their project. Same with the dspublisher/docs-theme/init.js file.
  • The [discussion-id] line should be removed from all content pages.
  • A lot of broken cross references in the pages. Some are likely due to the duplicate content in the "Foundation" section.
  • A missing include file (looks like this part of the pick script is not working https://github.com/vaadin/docs/blob/latest/scripts/pick/cherry-pick-config.js#L108-L111):
    error /Users/jouni/Downloads/dsp-test/myds-docs/articles/ds/components/grid/flow.asciidoc, line 36 - include file not found: /Users/jouni/Downloads/dsp-test/myds-docs/articles/ds/binding-data/_items-identities.adoc
    
  • All pass:[<!-- vale ... -->] lines should be removed
  • What should we do with components behind feature flags? Should those be included, and how should they be documented then?

jouni avatar May 09 '23 07:05 jouni