Add docs engine #45

rogermparent · 2022-04-23T16:16:57Z

Extends #43

Adds @dvcorg/gatsby-theme-iterative, which includes all the code and assets of dvc.org's blog engine, along with a lot of opinions from dvc.org that break the site a bit.

rogermparent · 2022-04-23T16:19:32Z

gatsby-config.js

    },
-    'gatsby-transformer-sharp',
-    'gatsby-plugin-sharp',
-    'gatsby-plugin-preact',


Preact breaks with React 18 installed, since Gatsby attempts to use the renderToPipeableStream API that Preact does not have.

Ways to solve are:

Remove Preact plugin

Downgrade to React 17

I've opted for the first for now, I'll try the second and contrast the resulting sites in Lighthouse to see which is more performant between Preact and React 18.

rogermparent · 2022-04-23T16:20:04Z

tailwind.config.js

+  content: [
+    './src/**/*.js',
+    './src/**/*.jsx',
+    './src/**/*.ts',
+    './src/**/*.tsx'
+  ],
+  darkMode: 'media',


Tailwind schema changed in an update

src/components/NavBar/index.tsx

rogermparent · 2022-04-23T16:21:18Z

gatsby-config.js

@@ -7,39 +7,15 @@ module.exports = {
      ? `https://${process.env.HEROKU_APP_NAME}.herokuapp.com`
      : 'https://mlem.ai',
    twitterUsername: '@DVCorg',
-    titleTemplate: '%s | MLEM'
+    titleTemplate: '%s | MLEM',
+    keywords: ['mlem']


theme requires keywords, we probably will want better ones.

Studies show that keywords don't realy make a difference in the site. We can probably just add a couple like mlem, ml, and ml deployment.

rogermparent · 2022-04-23T16:23:09Z

gatsby-config.js

      resolve: 'gatsby-plugin-manifest',
      options: {


Adding the theme to this site reminded me that manifest is going to be pretty unique across even sites with the same theme, so I've removed it from the theme and it must be manually specified.

We can probably find a more streamlined way to handle the manifest and ensure it mandates all the fields we want (favicons come to mind)

rogermparent · 2022-04-25T19:30:49Z

Sorry for any notification spam that may have happened here, I was trying to get Gatsby Cloud to catch onto this pre-existing PR.

Lessons learned:

The PR must be targeted onto master to be detected by the build system
Reopening and re-closing works
I toggled draft off, but that didn't work without re-targeting the PR

gatsby-cloud · 2022-04-25T19:34:04Z

Gatsby Cloud Build Report

mlem.ai

🎉 Your build was successful! See the Deploy preview here.

Build Details

View the build logs here.

🕐 Build time: 1m

Performance

Lighthouse report

Metric	Score
Performance	💚 95
Accessibility	🔶 88
Best Practices	💚 100
SEO	🔶 83

🔗 View full report

julieg18

Great job so far! The docs have definitely come a long way since the pr was first created. Minus a couple bugs I spotted, everything else looks to be working correctly!

src/components/Footer/index.tsx

julieg18 · 2022-05-17T14:50:26Z

src/@dvcorg/gatsby-theme-iterative/components/Documentation/RightPanel/index.tsx

@@ -0,0 +1,224 @@
+import React, { useState, useEffect, useRef } from 'react'


The border line in the content list is missing some margin:

src/@dvcorg/gatsby-theme-iterative/components/Documentation/Layout/index.tsx

content/docs/index.md

rogermparent · 2022-05-18T22:03:39Z

Alright, we have lint checks and pass them, time to clean up the last few issues from @julieg18's review and we should be good to go!

jorgeorpinel · 2022-05-18T22:54:52Z

Question: where is the docs engine repo? Maybe we should move some questions, issues, etc. to it. E.g. #59 (comment) or #43 (comment).

rogermparent · 2022-05-18T23:22:11Z

where is the docs engine repo?

https://github.com/iterative/gatsby-theme-iterative, though many changes will be done in this PR and backported in the interest of speed.

jorgeorpinel · 2022-05-19T19:46:53Z

I get a 404.

rogermparent · 2022-05-19T20:48:29Z

Sorry about that, I forgot that access was limited! I've added read permissions for the docs team on the theme repo, the same link should work now.

julieg18

Found a couple of other small bugs and had a question about the CSS.

julieg18 · 2022-05-20T12:56:02Z

src/styles/media.css

@@ -1,3 +1,4 @@
-@custom-media --sm-scr (min-width: 414px);
+@custom-media --xs-scr (max-width: 572px);


If I'm understanding things correctly, the reason the mobile styles we're breaking was because the CSS in our docs theme relies on this media.css?

If that's the case, shouldn't the CSS in the docs theme either use it's own media.css or just not have one at all if it's easier to impliment. The media.css that the docs theme normally relies on is very different from ours:

'--xxs-scr': '(max-width: 376px)', '--xs-scr': '(max-width: 572px)', '--sm-scr': '(max-width: 768px)', '--md-scr': '(max-width: 1004px)', '--lg-scr': '(min-width: 1005px)', '--xl-scr': '(min-width: 1200px)'

You're correct, this set of media queries was made as a compromise that fixes the breaks between the proper mobile-first tailwind-based media queries on mlem.ai and the postcss-custom-media queries from dvc.org that are mixed between max-width and min-width. The docs theme does need media queries since the docs themselves depend on them, but we definitely can use a more elegant implementation.

julieg18 · 2022-05-20T13:01:14Z

src/@dvcorg/gatsby-theme-iterative/components/Documentation/RightPanel/index.tsx

@@ -0,0 +1,224 @@
+import React, { useState, useEffect, useRef } from 'react'
+import cn from 'classnames'


The github button isn't staying at the top of the page:

julieg18 · 2022-05-20T13:04:40Z

src/@dvcorg/gatsby-theme-iterative/components/Documentation/Layout/index.tsx

+          }}
+        />
+      </div>
+      <div className={styles.content}>


For some reason, the left sidebar is spliing into the content:

julieg18 · 2022-05-20T13:08:23Z

Sorry about that, I forgot that access was limited! I've added read permissions for the docs team on the theme repo, the same link should work now.

Shouldn't the entire company have read or even write permissions by default?

rogermparent · 2022-05-20T16:13:25Z

Shouldn't the entire company have read or even write permissions by default?

Not sure if that's the intention, but if it is then that wasn't the case for this one- I had to add the Websites team a while ago in similar fashion to the docs team now. I vaguely remember something about SOC2 compliance leading us in the direction of keeping private repos accessible only to those that have a reason to access them, so that could explain why the defaults are how they are if it's purposeful.

If we want to give everyone in the organization access by default, I believe a "Base Role" has to be added. I can see there's no Base Role on this repo, but if we want to set one we'll need an Organization Owner to do so.

julieg18

While we do have some bugs that need to get taken care of, since the engine is basically done, we should be good to merge as a first iteration!

julieg18 · 2022-05-20T16:16:56Z

content/docs/index.md

@@ -0,0 +1,38 @@
+# MLEM Documentation


We could keep this page as is or maybe put a note somewhere that the rest of the docs are coming soon 🤔

rogermparent · 2022-05-20T16:17:17Z

While there's still a few styling issues, we're pretty sure all the showstoppers have been handed so we've decided to merge this PR into mlem.ai and take care of the rest in follow-ups. This should make it easier to make more normal PRs both for us and @iterative/docs instead of keeping up the massive long-lived PRs like this and #43.

julieg18 · 2022-05-20T16:24:28Z

If we want to give everyone in the organization access by default, I believe a "Base Role" has to be added. I can see there's no Base Role on this repo, but if we want to set one we'll need an Organization Owner to do so.

You can use our @"iterative/all" (added double quotes so I don't actually ping everybody 😅) to give everyone access. This is how it looks in mlem.ai:

rogermparent · 2022-05-20T16:32:19Z

I hadn't thought of that! I wasn't able to see other repo's permissions so I wasn't sure what the standard is.
Here's what the theme repo looks like now:

Thanks @julieg18!

mike0sv and others added 4 commits April 14, 2022 21:35

documentation stubs

6585bc2

docs structure

c879e62

Add gatsby-theme-iterative

45d27ec

Remove preact in favor of React 18

f7f9e02

rogermparent changed the base branch from main to docs-content April 23, 2022 16:17

rogermparent commented Apr 23, 2022

View reviewed changes

src/components/NavBar/index.tsx Outdated Show resolved Hide resolved

rogermparent commented Apr 23, 2022

View reviewed changes

rogermparent closed this Apr 25, 2022

rogermparent reopened this Apr 25, 2022

rogermparent marked this pull request as ready for review April 25, 2022 19:22

rogermparent closed this Apr 25, 2022

rogermparent reopened this Apr 25, 2022

rogermparent changed the base branch from docs-content to main April 25, 2022 19:24

rogermparent closed this Apr 25, 2022

rogermparent reopened this Apr 25, 2022

rogermparent added 7 commits April 25, 2022 15:46

Apply list-style: none where necessary

be5a6a4

Fix header by adding a container and bg color

e8f6d1f

Move Header and Footer into theme global with containers

e007489

Merge branch 'main' of github.com:iterative/mlem.ai into docs-engine

14bdc98

Use old site's custom media config

436c3a0

Add docs link

b6d0c20

Add header, font, and GH link fixes

6881860

rogermparent mentioned this pull request Apr 27, 2022

Fixes for fonts iterative/gatsby-theme-iterative#5

Merged

rogermparent added 2 commits April 27, 2022 16:51

Upgrade theme package

13c4708

Add sidebar stub

9dc8af1

rogermparent added 2 commits May 13, 2022 14:34

Run prettier

a7fdd10

Fix ts lint issues in project code

110cbaf

julieg18 reviewed May 17, 2022

View reviewed changes

aguschin reviewed May 18, 2022

View reviewed changes

content/docs/index.md Show resolved Hide resolved

Make further changes required to make linting pass

f010c3f

rogermparent added 2 commits May 18, 2022 18:06

Fix top margin on footer

d13ed3f

Merge branch 'main' of github.com:iterative/mlem.ai into docs-engine

5fe10aa

rogermparent added 3 commits May 19, 2022 17:04

Upgrade packages

774d646

Add xs-scr media query

17bd0c8

Merge branch 'main' of github.com:iterative/mlem.ai into docs-engine

1ffb064

julieg18 reviewed May 20, 2022

View reviewed changes

julieg18 approved these changes May 20, 2022

View reviewed changes

Add docs page stub

e7fe56c

rogermparent merged commit 8c0258e into main May 20, 2022

rogermparent deleted the docs-engine branch May 20, 2022 18:10

rogermparent mentioned this pull request May 20, 2022

Fix alert bar #62

Closed

yathomasi mentioned this pull request May 25, 2022

prism: we need both dvc and mlem highlighters #59

Closed

rogermparent mentioned this pull request May 25, 2022

Add docs engine #28

Closed

jorgeorpinel added A: docs Area: user documentation (gatsby-theme-iterative) A: website Website development labels Dec 2, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs engine #45

Add docs engine #45

rogermparent commented Apr 23, 2022

rogermparent Apr 23, 2022

rogermparent Apr 23, 2022

rogermparent Apr 23, 2022

julieg18 May 17, 2022

rogermparent Apr 23, 2022

rogermparent commented Apr 25, 2022

gatsby-cloud bot commented Apr 25, 2022 •

edited

julieg18 left a comment •

edited

julieg18 May 17, 2022

rogermparent commented May 18, 2022

jorgeorpinel commented May 18, 2022 •

edited

rogermparent commented May 18, 2022

jorgeorpinel commented May 19, 2022

rogermparent commented May 19, 2022

julieg18 left a comment

julieg18 May 20, 2022

rogermparent May 20, 2022 •

edited

julieg18 May 20, 2022

julieg18 May 20, 2022

julieg18 commented May 20, 2022 •

edited

rogermparent commented May 20, 2022 •

edited

julieg18 left a comment

julieg18 May 20, 2022

rogermparent commented May 20, 2022

julieg18 commented May 20, 2022

rogermparent commented May 20, 2022

		@@ -0,0 +1,224 @@
		import React, { useState, useEffect, useRef } from 'react'

		@@ -1,3 +1,4 @@
		@custom-media --sm-scr (min-width: 414px);
		@custom-media --xs-scr (max-width: 572px);

		@@ -0,0 +1,224 @@
		import React, { useState, useEffect, useRef } from 'react'
		import cn from 'classnames'

Add docs engine #45

Add docs engine #45

Conversation

rogermparent commented Apr 23, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rogermparent commented Apr 25, 2022

gatsby-cloud bot commented Apr 25, 2022 • edited

Gatsby Cloud Build Report

Build Details

Performance

Lighthouse report

julieg18 left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rogermparent commented May 18, 2022

jorgeorpinel commented May 18, 2022 • edited

rogermparent commented May 18, 2022

jorgeorpinel commented May 19, 2022

rogermparent commented May 19, 2022

julieg18 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rogermparent May 20, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

julieg18 commented May 20, 2022 • edited

rogermparent commented May 20, 2022 • edited

julieg18 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rogermparent commented May 20, 2022

julieg18 commented May 20, 2022

rogermparent commented May 20, 2022

gatsby-cloud bot commented Apr 25, 2022 •

edited

julieg18 left a comment •

edited

jorgeorpinel commented May 18, 2022 •

edited

rogermparent May 20, 2022 •

edited

julieg18 commented May 20, 2022 •

edited

rogermparent commented May 20, 2022 •

edited