Prepare API generator for automatic check

[Akirathan]

Pull Request Description

First step of #10507. Preparations for the Standard.Base API check job that will be introduced in a follow-up PR. In this PR, the functionality of DocsEmitSignatures is modified and tested such that its generated signatures for a module is ready for usage in the API check job. Most importantly, the signatures are sorted.

Sorting of the generated signatures prevents future false-positive failures of the API check job when somebody just reorders items in a module.

Important Notes

Further modifications to DocsEmitSignatures:

• Every definition in a module is represented as a list item in the Markdown for convenient rendering.
• Synthetic and empty modules are skipped.
• The directory structure of the generated docs/api corresponds to the directory structure in src.
  • Previously, it was docs/api/Standard/Base/Any.md but now it is just docs/api/Any.md (which was generated from src/Any.enso).

Example output is:

## Enso Signatures 1.0
## module Standard.Base.System.File
- type File
    - / self subpath:Standard.Base.Data.Text.Text -> Standard.Base.Any.Any
    - absolute self -> Standard.Base.Any.Any
    - copy_to self destination:Standard.Base.System.File.Generic.File_Like.File_Like replace_existing:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
    - create_directory self -> Standard.Base.Any.Any
    - create_dry_run_file self copy_original:Standard.Base.Any.Any= -> Standard.Base.Any.Any
    - create_temporary_file prefix:Standard.Base.Any.Any= suffix:Standard.Base.Any.Any= -> Standard.Base.Any.Any
    - creation_time self -> Standard.Base.Any.Any
    - current_directory -> Standard.Base.Any.Any
    - delete self recursive:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
    - delete_if_exists self recursive:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
    - exists self -> Standard.Base.Any.Any
    - extension self -> Standard.Base.Any.Any
    - home -> Standard.Base.Any.Any
    - is_absolute self -> Standard.Base.Any.Any
    - is_data_link self -> Standard.Base.Data.Boolean.Boolean
    - is_descendant_of self other:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - is_directory self -> Standard.Base.Any.Any
    - is_regular_file self -> Standard.Base.Any.Any
    - is_writable self -> Standard.Base.Any.Any
    - join self subpaths:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - last_modified_time self -> Standard.Base.Any.Any
    - list self name_filter:Standard.Base.Data.Text.Text= recursive:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
    - list_immediate_children self -> Standard.Base.Any.Any
    - move_to self destination:Standard.Base.System.File.Generic.File_Like.File_Like replace_existing:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
    - name self -> Standard.Base.Any.Any
    - new path:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - normalize self -> Standard.Base.Any.Any
    - parent self -> Standard.Base.Any.Any
    - path self -> Standard.Base.Any.Any
    - posix_permissions self -> Standard.Base.Any.Any
    - read self format:Standard.Base.Any.Any= on_problems:Standard.Base.Errors.Problem_Behavior.Problem_Behavior= -> Standard.Base.Any.Any
    - read_bytes self -> Standard.Base.Any.Any
    - read_first_bytes self n:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - read_last_bytes self n:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - read_text self encoding:Standard.Base.Data.Text.Encoding.Encoding= on_problems:Standard.Base.Errors.Problem_Behavior.Problem_Behavior= -> Standard.Base.Any.Any
    - relativize self child:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - resolve self subpath:Standard.Base.Data.Text.Text -> Standard.Base.Any.Any
    - resolve_single_part self part:Standard.Base.Data.Text.Text -> Standard.Base.Any.Any
    - size self -> Standard.Base.Any.Any
    - starts_with self parent:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - to_display_text self -> Standard.Base.Any.Any
    - to_js_object self -> Standard.Base.Any.Any
    - to_text self -> Standard.Base.Any.Any
    - with_input_stream self open_options:Standard.Base.Data.Vector.Vector action:Standard.Base.Any.Any -> Standard.Base.Any.Any
    - with_output_stream self open_options:Standard.Base.Data.Vector.Vector action:Standard.Base.Any.Any -> Standard.Base.Any.Any
- file_as_java file:Standard.Base.System.File.File -> Standard.Base.Any.Any
- file_types -> Standard.Base.Any.Any
- find_extension_from_name name:Standard.Base.Any.Any -> Standard.Base.Any.Any
- get_child_widget file:Standard.Base.Any.Any -> Standard.Base.Any.Any
- list_descendants file:Standard.Base.Any.Any -> Standard.Base.Any.Any
- resolve_local_file path:Standard.Base.Data.Text.Text -> Standard.Base.Any.Any
- Standard.Base.System.File.File.from that:Standard.Base.Data.Text.Text -> Standard.Base.System.File.File
- Standard.Base.System.File.Generic.File_Like.File_Like.from that:Standard.Base.System.File.File -> Standard.Base.System.File.Generic.File_Like.File_Like
- Standard.Base.System.File.Generic.Writable_File.Writable_File.from that:Standard.Base.System.File.File -> Standard.Base.System.File.Generic.Writable_File.Writable_File
- Standard.Base.Enso_Cloud.Data_Link.Data_Link_From_File.from that:Standard.Base.System.File.File -> Standard.Base.Enso_Cloud.Data_Link.Data_Link_From_File

Checklist

Please ensure that the following checklist has been satisfied before submitting the PR:

• The documentation has been updated, if necessary.
• Screenshots/screencasts have been attached, if there are any visual changes. For interactive or animated visual changes, a screencast is preferred.
• All code follows the
  Scala,
  Java,
  TypeScript,
  and
  Rust
  style guides. In case you are using a language not listed above, follow the Rust style guide.
• Unit tests have been written where possible.
• If meaningful changes were made to logic or tests affecting Enso Cloud integration in the libraries,
  or the Snowflake database integration, a run of the Extra Tests has been scheduled.
  • If applicable, it is suggested to paste a link to a successful run of the Extra Tests.

[JaroslavTulach]

Maybe we could select the directory based on the "type of documentation" - e.g. api for --docs=api and md for --docs or --docs=md

[JaroslavTulach]

Skipping namespace and name from the directory structure? That is probably good idea. CCing @radeusgd

[Akirathan]

The idea is that the directory hierarchy under docs/api should follow the one in src. It is tested in

enso/engine/runtime-integration-tests/src/test/java/org/enso/compiler/dump/test/DocsGenerateTest.java

Lines 282 to 312 in 30904f6

	@Test
	public void generatedSignaturesForProject_HasSameDirectoryHierarchyAsSources()
	throws IOException {
	var projName = "Proj";
	var modules =
	Set.of(
	new SourceModule(QualifiedName.fromString("Main"), "main = 42"),
	new SourceModule(QualifiedName.fromString("Subdir.Submodule"), "submodule = 42"));
	var projDir = TEMP.newFolder(projName);
	ProjectUtils.createProject(projName, modules, projDir.toPath());
	ProjectUtils.generateProjectDocs(
	"api",
	ContextUtils.defaultContextBuilder(),
	projDir.toPath(),
	ctx -> {
	var ensoCtx = ContextUtils.leakContext(ctx);
	var pkg =
	ensoCtx
	.getPackageRepository()
	.getPackageForLibrary(LibraryName.apply("local", projName));
	assertThat(pkg.isDefined(), is(true));
	var signatureOutDir = DocsGenerate.defaultOutputDir(pkg.get());
	assertThat(
	"Default output dir for signatures was created", signatureOutDir.exists(), is(true));
	var srcDir = pkg.get().sourceDir();
	assertThat(srcDir.resolve("Main.enso").exists(), is(true));
	assertThat(signatureOutDir.resolve("Main.md").exists(), is(true));
	assertThat(srcDir.resolve("Subdir").resolve("Submodule.enso").exists(), is(true));
	assertThat(signatureOutDir.resolve("Subdir").resolve("Submodule.md").exists(), is(true));
	});
	}