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

docs_main.cr is a mess #14625

Open
straight-shoota opened this issue May 24, 2024 · 4 comments · May be fixed by #15621
Open

docs_main.cr is a mess #14625

straight-shoota opened this issue May 24, 2024 · 4 comments · May be fixed by #15621
Labels
kind:docs status:discussion

Comments

@straight-shoota
Copy link
Member

docs_main.cr serves as entry point to generate the API docs for the standard library. It requires all files that contain documented features.

It's quite a chaotic mess.

Entries are unordered. That's probably due to some forced order dependencies, not sure about the details.

Many entries are omitted because they're already required as part of the prelude or are transitive dependencies of others. This makes it hard to follow which files actually end up being included in the docs.

There's generally quite a bit of overlap with prelude.cr. But it's inconsistent because some parts of the prelude are also in docs_main.cr (require "array") while others aren't (require "base64").
It would be cleaner to either embrace the prelude and remove duplicates, or spell out all requires in docs_main.cr explicitly and even remove the prelude from the docs build (crystal docs src/docs_main.cr --prelude=empty).
I don't think removing the prelude makes much sense. It would allow us to exclude files that don't contain any documented features, but they might be implicit requirements of other code that's relevant for documentation.

It would also be helpful to have a reminder to ensure newly added files are present in docs_main.cr. That's a relatively rare event, so we don't always remember it (see #14624). Most new files are added to paths like src/compiler, src/crystal or src/lib_c anyway, which can be ignored for docs.
Not sure if there's an easy way to do this, though. It might not be terribly relevant because we should usually notice if API docs are missing when preparing the release notes, so we should be able to fix it in time before a release.

So I'd suggest to do the following:

  • Remove all entries in docs_main.cr which are already in prelude.cr.
  • Order all entries in docs_main.cr by path. If there are any forced order exceptions, document them (like in prelude.cr).
  • Consider if we can add some kind of automation to alert us of adding new files to docs_main.cr.
@ysbaddaden
Copy link
Contributor

I wish we had a folder for std (e.g. src/std), then docs_main.cr could be (almost) reduced to:

require "./annotations"
require "./compiler/crystal/macros"
require "./std/*"
require "./docs_pseudo_methods"

@straight-shoota straight-shoota linked a pull request Apr 1, 2025 that will close this issue
Draft
@straight-shoota
Copy link
Member Author

This actually works relatively decent if we use ./* (i.e. the entire src folder) instead of ./std/*. This folder does not contain any files that must be excluded from doc generation (except maybe empty.cr, but we can skip that explicitly). All compiler code lies in ./compiler/.

Some of the top-level files won't implicitly include all files in their parts of the stdlib. There is not even a compress.cr, so instead of require "compress" you need to select specific implementations such as compress/gzip.
Serialization options and spec helpers are also often only available with an explicit require, such as require "uri/json" or require "log/spec".
A simple wildcard require won't be able to pick them up. So we must include some specific subpaths. But that's certainly better than explicitly listing all files.
If we moved all stdlib into a subfolder, maybe we could require the entire tree with require "std/**".

@straight-shoota
Copy link
Member Author

straight-shoota commented Apr 1, 2025 •
edited
Loading

See #15621 for an implementation.
The result of make docs is identical, except for a couple of files which were legitimately missing from docs_main.cr are added now. 🚀

  • spec.cr - which includes the entire module documentation for Spec
  • uri/yaml.cr
  • uuid/yaml.cr

big/yaml.cr, big/json.cr and log/json.cr were also missing, but didn't get included by ./*.

@straight-shoota
Copy link
Member Author

A full tree require with require "std/**" would be difficult. We have many files implementing alternative strategies, which are mutually exclusive and generally shouldn't be mixed. That affects many files in crystal/system, lib_c bindings, exception/call_stack/*.
Other files such as ecr/process.cr are not part of the stdlib API at all.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
kind:docs status:discussion
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Simplify docs_main.cr straight-shoota/crystal
2 participants
@ysbaddaden @straight-shoota