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

Update documentation for breaking changes and improve usability of examples #262

Closed
wants to merge 33 commits into from

Conversation

ablaom
Copy link
Collaborator

@ablaom ablaom commented Jun 11, 2024

In addition to updating docs to reflect breaking changes in MLJFlux 0.5.0 this PR:

  • fixes problems with docs/Project.toml that was causing doc generation to fail (silently, see Documentation generation can fail silently #261)
  • removes docs/Manifest.toml
  • adds readme.md files for the workflow examples, and also commits a Manifest.toml for each example, so users can get a reliable stable version of packages known to work with the notebooks appearing there (see more in todo below)
  • adds generate.jl file in each example for maintainers to use to generate all the notebooks from .jl source
  • (temporarily?) replaced @example fencing with @julia fencing in generated example markdown
  • updates examples/mnist
  • fixes missing pkg metadata for new binary classifier
  • fixes the spam example so that it actually runs (e.g., add missing stop_words)

To do:

  • Consider generating executed markdown for the examples (or re-instate @example fencing)
  • Add links from the examples to the github folders that contain the notebook, julia source and Manifest.toml, so these can be accessed from the Documenter documentation
  • Copy "examples/mnist" into "docs/src/work flows" (version in examples now flagged as "archived", ie not to be updated further)
  • Fix remaining Documenter warnings about missing links and so forth.
  • Add a README.md in examples/ pointing users to the examples sections of /docs
  • Add documentation badge and dump most of /README.MD and now redundant

@ablaom ablaom marked this pull request as draft June 11, 2024 07:13
@ablaom
Copy link
Collaborator Author

ablaom commented Jun 11, 2024

cc @EssamWisam

@EssamWisam
Copy link
Collaborator

cc @EssamWisam

Thanks for this significant effort 🙏. I may mention that the local version of the spam example works for me without defining an explicit list of stop words or changing anything. They directly come from Languages.jl.

In further commits in MLJFlux or elsewhere, I will try to ensure running the Julia formatter (not a habit yet).

@ablaom
Copy link
Collaborator Author

ablaom commented Jun 11, 2024

I may mention that the local version of the spam example works for me without defining an explicit list of stop words or changing anything. They directly come from Languages.jl.

Thanks for flagging! On further inspection I found a corrupted character (probably my bad) that explains my original problem but have re-instated the Languages.jl solution.

@ablaom ablaom mentioned this pull request Jun 12, 2024
@ablaom
Copy link
Collaborator Author

ablaom commented Jun 12, 2024

Closed in favour of #263

@ablaom ablaom closed this Jun 12, 2024
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.

2 participants