Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation Refactoring #526

Merged
merged 20 commits into from
May 6, 2024
Merged

Documentation Refactoring #526

merged 20 commits into from
May 6, 2024

Conversation

limarta
Copy link
Contributor

@limarta limarta commented Apr 17, 2024 •
edited
Loading

This PR restructures the documentation to somewhat resemble the "Documentation System" described here. Sections are organized as follows (see pages.jl) :

  • Home
  • Getting Started: This section is for brief and concise examples that a user is likely to be familiar with e.g. linear regression.
  • Tutorials: In-depth tutorials that highlight Gen. We further divide the sections into Basic and Advanced.
  • How-to Guides: This section lists snippets on "how to do x." These are not tutorials, so no introductory setup is expected.
  • API
    • Modeling Language API
    • Standard Inference API
  • Explanations and Internals: This section will serve as conceptual material relevant to the design and internals of Gen. Unlike the tutorials and How-to sections, this section offers theory and discussion about Gen for advanced users and is not strictly necessary to use Gen in applications.

Other additions:

  • The tutorials now use Documenter.jl's REPL feature to run Julia code. This feature allows tutorial writers to integrate code directly in the markdown files without having to write hardcoded outputs.
  • Ref links that were previously broken are now fixed.

@limarta limarta self-assigned this Apr 17, 2024
@limarta limarta requested a review from sritchie April 17, 2024 18:13
sritchie
sritchie requested changes Apr 17, 2024
View reviewed changes
docs/README Outdated Show resolved Hide resolved
docs/build_docs_locally.sh Show resolved Hide resolved
docs/make.jl Outdated Show resolved Hide resolved
docs/src/assets/header.js Show resolved Hide resolved
docs/src/misc/references.md Outdated Show resolved Hide resolved
docs/src/misc/contributing.md Outdated Show resolved Hide resolved
docs/src/misc/changelog.md Outdated Show resolved Hide resolved
docs/src/tutorials/languages/static_dsl.md Outdated Show resolved Hide resolved
docs/src/tutorials/vi.md Outdated Show resolved Hide resolved
@limarta limarta requested a review from ztangent April 29, 2024 17:15
@limarta
Copy link
Contributor Author

limarta commented Apr 30, 2024

Note that the changes here don't include all of the tutorials here. Later tutorial pushes can help convert the remaining tutorials into the required format for the new docs.

@limarta limarta requested a review from sritchie April 30, 2024 22:48
ztangent
ztangent reviewed May 1, 2024
View reviewed changes
docs/pages.jl Outdated
"Selections" => "api/model/selections.md",
"Optimizing Trainable Parameters" => "api/model/parameter_optimization.md",
"Trace Translators" => "api/model/trace_translators.md",
"Differential Programming" => "api/model/differential_programming.md"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be "Differentiable programming"! In both the label and the filename.

@ztangent
Copy link
Member

ztangent commented May 1, 2024

Thanks for this! I'll take a look when I have more time. Is there a link to a rendered version of the new docs, or will I have to build locally?

Also, flagging that if we merge #520 soon, this may require us to update the docs again. #520 should probably a breaking change to Gen.jl though (i.e. it should be released in Gen.jl 0.5.0) --- so my suggestion would be for us to finish this PR, and release the new docs together with Gen.jl 0.4.7, which will be a minor bugfix release with a few new features (e.g. #521, #524).

@limarta
Copy link
Contributor Author

limarta commented May 1, 2024

@ztangent It seems you have to build locally. Not sure why the dev site is not updating.

sritchie
sritchie approved these changes May 1, 2024
View reviewed changes
Copy link

@sritchie sritchie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

docs/src/tutorials/combinators.md Outdated

```@raw html
<div style="text-align:center">
<img src="../../images/recurse_combinator.png" alt="schematic of recurse combinatokr" width="70%"/>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo

docs/.gitignore
@@ -1 +0,0 @@
Manifest.toml
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why is this deleted?

Project.toml
@@ -34,4 +34,4 @@ julia = "1.6"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test"]
test = ["Test"]
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is the sort of whitespace change it's nice to not include in a code review...

@sritchie sritchie merged commit 95c797f into master May 6, 2024
3 of 4 checks passed
@sritchie sritchie deleted the doc_fix branch May 6, 2024 14:35
@sritchie
Copy link

sritchie commented May 6, 2024

NIce work @limarta !!

@ztangent ztangent mentioned this pull request Oct 5, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ztangent ztangent ztangent left review comments

@sritchie sritchie sritchie approved these changes

Assignees

@limarta limarta

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@limarta @ztangent @sritchie