[Docs] Add docs with `mkdocs` #202

smokestacklightnin · 2024-09-01T04:23:52Z

Google Would like to migrate the documentation for mlmd away from their internal systems, so this PR implements that migration.

Changes in this PR:

Add .gitignore to the project
Add mkdocs to the dependencies and add a configuration for it
Add a GitHub workflow to deploy the documentation on GitHub Pages
Add __all__ variables so modules and their members are recognized by mkdocs
Fixed notes admonitions
Add white background to rendered png images so they are legible in dark mode

TODO:

Fix the triggers before merge
Find a solution for including members of the proto submodule

peytondmurray · 2024-10-01T21:39:44Z

I made a few additional changes:

Renamed g3doc -> docs, since we are no longer using internal tooling for building documentation and docs is the standard mkdocs documentation directory
Modified the .gitignore to include bazel-* build artifacts
Updated the workflow to build docs on python 3.12
Enabled building and publishing docs on pushes to master

peytondmurray · 2024-10-01T21:44:33Z

ml_metadata/__init__.py

+__all__ = [
+  "downgrade_schema",
+  "ListOptions",
+  "MetadataStore",
+  "OrderByField",
+]


This isn't in scope for this PR, but the try/except block above doesn't work. In the event of an ImportError, this module won't be able to export these symbols. I can't really tell what is intended by the try/except block swallowing any import errors, but maybe this is something we can clean up in a future PR.

This seems to have been present since before we started working on the repo.

I agree with you that we can possibly revisit this in a future PR

peytondmurray · 2024-10-01T21:55:41Z

ml_metadata/proto/__init__.py

 del metadata_store_service_pb2
 del metadata_store_service_pb2_grpc


If you're going to remove the del metadata_store_pb2 line, can you also remove these other two?

Just a note of context for others working on this: I'm assuming this is to "un-import" the imported protobuf modules...but I'm not clear on why this is needed. If the goal is to re-export certain symbols, from <module> import <symbol> is sufficient. del <module> doesn't "un-import" the module - it persists elsewhere. See https://mail.python.org/pipermail/tutor/2006-August/048596.html for details.

I removed del metadata_store_pb2 because as it is currently written, it is not imported directly anymore. It just has member objects imported. I left the other two del statements because they are not used to import member objects. My preference is to leave them as they are and revisit them in the future.

.github/workflows/cd-docs.yml

peytondmurray

A few minor changes/questions. Once those are done, if you've checked that this deploys and looks good, then let's ship it! 🚢

smokestacklightnin · 2024-10-02T00:21:25Z

.github/workflows/cd-docs.yml

+    branches:
+      - master


@peytondmurray I think we should allow this to run for push on any branch so developers can preview the deployment from their forks. If we make the reasonable assumption that nobody is pushing directly to upstream/master, then this will not affect the main docs deployment.

Right now we have no way of deploying builds of individual branches - for now it is up to the users to build the docs and examine their changes locally, and for reviewers to pay due diligence in asking PR authors to provide screenshots/description of major changes to the docs.

Nobody will be pushing to master, but we still want this enabled so that when github itself makes a merge commit and pushes it to master the docs will be rebuilt. As it stands every PR will force-push to gh-pages.

smokestacklightnin · 2024-10-02T01:05:24Z

@peytondmurray fixed merge conflict and marked as ready for review

.github/workflows/cd-docs.yml

peytondmurray

Thanks for this 🚀

XinranTang · 2024-10-09T18:58:29Z

Hi, could you please resolve the conflicts in this branch?

Add pre-commit and associated CI

Links do not work because API for `mlmd.proto` is not showing up yet. Links will work when this is fixed

smokestacklightnin · 2024-10-15T07:50:17Z

Hi, could you please resolve the conflicts in this branch?

Done

CC: @peytondmurray

peytondmurray · 2024-10-23T22:46:33Z

@XinranTang Is there anything else I can do to push this through? It would be nice to get this merged.

smokestacklightnin · 2024-10-24T22:15:23Z

@XinranTang Thanks for merging this.

Can you please change the publishing branch to gh-pages so the docs can correctly be deployed? I'd do it myself but I don't have permissions.

XinranTang · 2024-10-30T23:48:33Z

@smokestacklightnin Done https://github.com/google/ml-metadata/settings/pages

smokestacklightnin · 2024-10-31T03:04:19Z

Thanks @XinranTang!

I somehow overlooked adding some of the documentation content to the branch before opening the PR. I have added it now in PR #208. Can you please review and merge it? Sorry for the confusion.

smokestacklightnin marked this pull request as draft September 9, 2024 16:22

smokestacklightnin changed the title ~~Add docs with mkdocs~~ [WIP] Add docs with mkdocs Sep 10, 2024

smokestacklightnin force-pushed the ci/docs/add-docs branch 8 times, most recently from 1c206ec to 260a824 Compare September 30, 2024 01:23

peytondmurray force-pushed the ci/docs/add-docs branch from 5b16a7a to b96b18b Compare October 1, 2024 21:39

peytondmurray reviewed Oct 1, 2024

View reviewed changes

.github/workflows/cd-docs.yml Outdated Show resolved Hide resolved

peytondmurray suggested changes Oct 1, 2024

View reviewed changes

smokestacklightnin commented Oct 2, 2024

View reviewed changes

smokestacklightnin force-pushed the ci/docs/add-docs branch from 6bb2e31 to a4d2b20 Compare October 2, 2024 00:53

smokestacklightnin marked this pull request as ready for review October 2, 2024 00:56

smokestacklightnin force-pushed the ci/docs/add-docs branch from a4d2b20 to ca825a5 Compare October 2, 2024 01:04

peytondmurray suggested changes Oct 2, 2024

View reviewed changes

.github/workflows/cd-docs.yml Show resolved Hide resolved

peytondmurray approved these changes Oct 3, 2024

View reviewed changes

XinranTang and others added 6 commits October 15, 2024 00:31

Merge pull request google#204 from peytondmurray/17-lint-workflow

49dc26a

Add pre-commit and associated CI

Add mkdocs as optional dependency

79eb203

Add mkdocs.yml along with all necessary files

34d7b80

Move icon to images folder

0d9e6d6

Add workflow to deploy docs

15a7747

Ignore test modules

d6a4e36

smokestacklightnin added 18 commits October 15, 2024 00:43

Use indentation instead of slash character \

941dfe0

Add overview from mlmd.errors api docs

a510016

Add show_if_no_docstring option to mlmd.errors

2649a31

Use spaces instead of tabs

f5b18b8

Add overview with links.

4802bb2

Links do not work because API for `mlmd.proto` is not showing up yet. Links will work when this is fixed

Add link to tutorial

47960a4

Fix repo name

ead6757

Rename root.md to index.md

18875d8

Change links to point internally

f5de8a5

Remove logo

61b75e9

Fix broken link

946ef60

Fix admonitions

50ed6c1

Add white background to png files

3844057

Add build docs check on pull request

a3adca3

Remove --verbose flag

7f63761

Fix triggers

4c2ead1

Fix link

040369b

Only trigger on push to master

4525700

smokestacklightnin force-pushed the ci/docs/add-docs branch from 303f72f to 4525700 Compare October 15, 2024 07:48

smokestacklightnin changed the title ~~[WIP] Add docs with mkdocs~~ [Docs] Add docs with mkdocs Oct 16, 2024

rtg0795 requested a review from XinranTang October 16, 2024 23:16

Fix linting errors

aea4660

XinranTang merged commit 398994b into google:master Oct 24, 2024
3 checks passed

peytondmurray deleted the ci/docs/add-docs branch October 31, 2024 01:16

smokestacklightnin mentioned this pull request Oct 31, 2024

Add missing docs content to git #208

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs] Add docs with `mkdocs` #202

[Docs] Add docs with `mkdocs` #202

smokestacklightnin commented Sep 1, 2024 •

edited

Loading

peytondmurray commented Oct 1, 2024 •

edited

Loading

peytondmurray Oct 1, 2024

smokestacklightnin Oct 2, 2024

peytondmurray Oct 1, 2024 •

edited

Loading

smokestacklightnin Oct 2, 2024

peytondmurray left a comment

smokestacklightnin Oct 2, 2024

peytondmurray Oct 2, 2024

smokestacklightnin commented Oct 2, 2024

peytondmurray left a comment

XinranTang commented Oct 9, 2024

smokestacklightnin commented Oct 15, 2024 •

edited

Loading

peytondmurray commented Oct 23, 2024

smokestacklightnin commented Oct 24, 2024

XinranTang commented Oct 30, 2024

smokestacklightnin commented Oct 31, 2024 •

edited

Loading

		del metadata_store_service_pb2
		del metadata_store_service_pb2_grpc

[Docs] Add docs with mkdocs #202

[Docs] Add docs with mkdocs #202

Conversation

smokestacklightnin commented Sep 1, 2024 • edited Loading

peytondmurray commented Oct 1, 2024 • edited Loading

peytondmurray Oct 1, 2024

Choose a reason for hiding this comment

smokestacklightnin Oct 2, 2024

Choose a reason for hiding this comment

peytondmurray Oct 1, 2024 • edited Loading

Choose a reason for hiding this comment

smokestacklightnin Oct 2, 2024

Choose a reason for hiding this comment

peytondmurray left a comment

Choose a reason for hiding this comment

smokestacklightnin Oct 2, 2024

Choose a reason for hiding this comment

peytondmurray Oct 2, 2024

Choose a reason for hiding this comment

smokestacklightnin commented Oct 2, 2024

peytondmurray left a comment

Choose a reason for hiding this comment

XinranTang commented Oct 9, 2024

smokestacklightnin commented Oct 15, 2024 • edited Loading

peytondmurray commented Oct 23, 2024

smokestacklightnin commented Oct 24, 2024

XinranTang commented Oct 30, 2024

smokestacklightnin commented Oct 31, 2024 • edited Loading

[Docs] Add docs with `mkdocs` #202

[Docs] Add docs with `mkdocs` #202

smokestacklightnin commented Sep 1, 2024 •

edited

Loading

peytondmurray commented Oct 1, 2024 •

edited

Loading

peytondmurray Oct 1, 2024 •

edited

Loading

smokestacklightnin commented Oct 15, 2024 •

edited

Loading

smokestacklightnin commented Oct 31, 2024 •

edited

Loading