Migrating documentation to fit with diataxis.fr approach #71

elijahbenizzy · 2023-02-26T02:08:56Z

[Short description explaining the high-level reason for the pull request]

Changes

How I tested this

Notes

Checklist

PR has an informative and human-readable title (this will be pulled into the release notes)
Changes are limited to a single goal (no scope creep)
Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
Any change in functionality is tested
New functions are documented (with a description, list of inputs, and expected output)
Placeholder code is flagged / future TODOs are captured in comments
Project documentation has been updated if adding/changing functionality.

This adds links to the tutorial, and cleans up pieces.

* Changes open source email address to the correct one * Fills out overview of concepts * Update docs/concepts/best-practices/function-modifiers.rst Co-authored-by: Stefan Krawczyk <stefan@dagworks.io> * Update docs/concepts/customizing-execution.rst Co-authored-by: Stefan Krawczyk <stefan@dagworks.io> * Update docs/concepts/decorators-overview.rst Co-authored-by: Stefan Krawczyk <stefan@dagworks.io> * Update docs/concepts/customizing-execution.rst Co-authored-by: Stefan Krawczyk <stefan@dagworks.io> * Update docs/concepts/decorators-overview.rst Co-authored-by: Stefan Krawczyk <stefan@dagworks.io> --------- Co-authored-by: Stefan Krawczyk <stefan@dagworks.io>

So that it's clear how to get started/install things and when to us myST and when to use reST.

Added extensions are for creating reference docs from our python files easily. Otherwise it adds the hamilton repo to the path when sphinx consumes conf.py. This will mean that the hamilton code is now accessible to be referenced for when we want to create documentation from those modules. Note: sphinx will need to have all the right python dependencies in order to be able to parse that python file.

So that you can change function doc and it'll rebuild the docs.

This is still WIP, but committing to be able to pull and update changes as needed.

This is probably good enough for now. This isn't a bad way to do things, it forces more documentation into the class string of the decorators. It also means that we cannot be sloppy in the reST string of constructors either.

This should subsume what was there previously. The docs themselves aren't that pretty -- they could use a little more whitespace. But otherwise good enough for now.

This is pretty basic. Still need to flesh out the function doc a bit.

We have documents with content to migrate.

So that way we can easily include the main README as the landing page for the documentation. Fixes blog, talks, posts to include newer content.

So that we catch weird indentation warnings in dev. Adds to requirements-docs.txt what readthedocs installs. Note with myst we can't use the latest sphinx docs.

elijahbenizzy changed the title ~~Adds basic instructions for building/running docs locally~~ Migrating documentation to fit with diataxis.fr approach Feb 26, 2023

elijahbenizzy and others added 15 commits February 26, 2023 21:08

Adds basic instructions for building/running docs locally

ce34bb2

Adds scaffolding for diataxis docs migration

a73d475

Reorganizes based on conversation with stefan

b808607

Changes to include mist + symlinking

4d597c2

Cleans up to remove old references to docs

30169ee

Polishes the "getting started" section o fthe new docs.

a7a2a46

This adds links to the tutorial, and cleans up pieces.

Adds how-to docs (#78)

2e1b58f

Adds sphinx-autobuild and updates docs/README.md

b4d4d3e

So that it's clear how to get started/install things and when to us myST and when to use reST.

Updates docs/README.md to use --watch argument

3e4df77

So that you can change function doc and it'll rebuild the docs.

Adds bones for API reference documentation section

fdb5732

This is still WIP, but committing to be able to pull and update changes as needed.

Completes MVP decorators reference API

9664f47

This is probably good enough for now. This isn't a bad way to do things, it forces more documentation into the class string of the decorators. It also means that we cannot be sloppy in the reST string of constructors either.

Adds graph-adapters and result builders to docs

99c105d

This should subsume what was there previously. The docs themselves aren't that pretty -- they could use a little more whitespace. But otherwise good enough for now.

Adds drivers to reference API

27c0d41

This is pretty basic. Still need to flesh out the function doc a bit.

skrawcz force-pushed the diataxis-docs branch from 595cd6a to 27c0d41 Compare February 27, 2023 05:10

skrawcz added 5 commits February 26, 2023 22:06

Fixes doc warnings

aebc335

We have documents with content to migrate.

Changes index.rst to index.md and other changes

9d0d272

So that way we can easily include the main README as the landing page for the documentation. Fixes blog, talks, posts to include newer content.

Deletes migrated docs and fixes more warnings

977e295

Adds more realistic command line args to readthedocs

64f25b5

So that we catch weird indentation warnings in dev. Adds to requirements-docs.txt what readthedocs installs. Note with myst we can't use the latest sphinx docs.

Fixes warnings from readthedocs to build docs

5ecae08

skrawcz marked this pull request as ready for review February 27, 2023 06:09

skrawcz merged commit d177113 into main Feb 27, 2023

skrawcz deleted the diataxis-docs branch February 27, 2023 06:10

skrawcz mentioned this pull request Feb 27, 2023

Testing to see whether we can autogenerate code reference docs #6

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrating documentation to fit with diataxis.fr approach #71

Migrating documentation to fit with diataxis.fr approach #71

elijahbenizzy commented Feb 26, 2023

Migrating documentation to fit with diataxis.fr approach #71

Migrating documentation to fit with diataxis.fr approach #71

Conversation

elijahbenizzy commented Feb 26, 2023

Changes

How I tested this

Notes

Checklist