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.

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

Transfer all high level docs from Turing.jl #375

Merged
merged 56 commits into from
Jul 7, 2023
Merged

Transfer all high level docs from Turing.jl #375

merged 56 commits into from
Jul 7, 2023

Conversation

yebai
Copy link
Member

@yebai yebai commented Jan 6, 2023

This PR transfers all high-level (i.e. non-API or doc-string) documentation from Turing.jl. This allows us to unify most docs and tutorials workflow and pave the way to simplify build steps (we only need standard Jekyll eventually) in the turing.ml repo.

Steps

  1. Merge this PR
  2. Setup MultiDocumenter and migrate all remaining library doc files in Turing.jl (maybe a subfolder multidoc within the turing.ml repo: Setup multidoc for Turing packages turinglang.github.io#41 preview)
  3. Simplify build scripts in turing.ml by removing all Documenter-specific scripts

TODO

  • group 0
  • group 1
  • group 2
  • group 3
  • group 4
  • group 5
  • group 6

@yebai yebai marked this pull request as draft January 6, 2023 20:35
@yebai yebai force-pushed the hg/transfer-docs branch 2 times, most recently from 040a0f6 to c614595 Compare January 26, 2023 17:05
@yebai
Copy link
Member Author

yebai commented Jan 26, 2023

@cgbotta I added default project files to all docs. The default environment only installs Turing and StatsPlots. This is likely insufficient for more complicated doc pages. Please feel free to add additional dependencies where needed.

@cgbotta
Copy link
Contributor

cgbotta commented Feb 2, 2023

When I try to weave the new tutorials using TuringTutorials.weave it only weaves the existing ones, but does not include the new ones we have added in this PR

I recall that there was one place where I needed to manually add new tutorials to the weave scripts, but this list seems to have been removed in @devmotion 's recent work. Am I overlooking something?

@yebai yebai mentioned this pull request Feb 2, 2023
@@ -0,0 +1,20 @@
---
Copy link
Member

Choose a reason for hiding this comment

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

This file does not contain any code or examples but is just a landing page on the webpage it seems, so I wonder:
Should this file be added here? Or should it be a regular markdown file? Or at least, do we really have to add Project.toml + Manifest.toml files here?

@devmotion
Copy link
Member

When I try to weave the new tutorials using TuringTutorials.weave it only weaves the existing ones, but does not include the new ones we have added in this PR

I recall that there was one place where I needed to manually add new tutorials to the weave scripts, but this list seems to have been removed in @devmotion 's recent work. Am I overlooking something

I guess you might refer to the manual list in the CompatHelper github action? The whole action was removed and replaced with an action that updates all Manifest.toml files (run once every week), so you're right, you don't have to add new tutorials/docs to some list anymore. However, that list was only relevant for CI (or more specifically CompatHelper) and completely independent from the weave commands (and basically everything else in the repo).

There were no changes to the weave commands after your PR it seems.

Regarding the new jmd files in this PR, it seems in the previous PR the non-tutorial jmd file was put in the tutorials folder but with a docs- prefix. Should we also somehow make it clear (e.g. by using a prefix) that these new jmd files are distinct from the tutorials, even though they are in the tutorials folder? Or maybe it would be better to move non-tutorials to a separate folder (docs?)?

@yebai yebai marked this pull request as ready for review June 11, 2023 21:03
yebai and others added 6 commits July 6, 2023 20:50
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@yebai yebai merged commit 0294372 into master Jul 7, 2023
@delete-merged-branch delete-merged-branch bot deleted the hg/transfer-docs branch July 7, 2023 19:12
@devmotion
Copy link
Member

I think this PR should not have been merged - I really think we should fix #394 before any other changes in this repo. Since it is not resolved all the docs and all the examples will be built and run with Julia 1.6 - but since Turing > 0.22 is not compatible with Julia 1.6 anymore, docs will be generated with a quite old version of Turing and in particular are not representative of the latest release (the versioning on the webpage has been misleading for a long time, even though the tutorials are listed as /v26/ they do not use Turing 0.26).

@yebai
Copy link
Member Author

yebai commented Jul 7, 2023

Merging this PR is an incremental step, but it doesn’t solve all problems. Next, we can make a concerted effort to upgrade all docs and tutorials to Julia 1.9.

@yebai
Copy link
Member Author

yebai commented Jul 7, 2023

Many thanks for the help, especially @cgbotta, who did most of the heavy work!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants