Skip to content

Documentation Refactoring#526

Merged
sritchie merged 20 commits intomasterfrom
doc_fix
May 6, 2024
Merged

Documentation Refactoring#526
sritchie merged 20 commits intomasterfrom
doc_fix

Conversation

@limarta
Copy link
Copy Markdown
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 suggested changes Apr 17, 2024
View reviewed changes
Comment thread docs/README
Comment thread docs/build_docs_locally.sh
Comment thread docs/make.jl Outdated
Comment thread docs/src/assets/header.js
Comment thread docs/src/misc/references.md Outdated
Comment thread docs/src/misc/contributing.md Outdated
Comment thread docs/src/misc/changelog.md Outdated
Comment thread docs/src/tutorials/languages/static_dsl.md Outdated
Comment thread docs/src/tutorials/vi.md Outdated
@limarta limarta requested a review from ztangent April 29, 2024 17:15
@limarta
Copy link
Copy Markdown
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
Comment thread 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
Copy Markdown
Member

@ztangent ztangent May 1, 2024

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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
Collaborator

@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!

Comment thread 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
Copy Markdown
Collaborator

@sritchie sritchie Apr 24, 2024

Choose a reason for hiding this comment

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

typo

Comment thread docs/.gitignore
@@ -1 +0,0 @@
Manifest.toml
Copy link
Copy Markdown
Collaborator

@sritchie sritchie May 1, 2024

Choose a reason for hiding this comment

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

why is this deleted?

Comment thread Project.toml

[targets]
test = ["Test"]
test = ["Test"] No newline at end of file
Copy link
Copy Markdown
Collaborator

@sritchie sritchie May 1, 2024

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
@sritchie sritchie deleted the doc_fix branch May 6, 2024 14:35
@sritchie
Copy link
Copy Markdown
Collaborator

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

+1 more reviewer

@sritchie sritchie sritchie approved these changes

Reviewers whose approvals may not affect merge requirements

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