Split standard library docs up one page per module. #5636

sofiafaro-da · 2020-04-20T15:48:44Z

This PR updates our standard library docs to put each module on its own page. Users can easily navigate the docs by using the table of contents on the left, or the standard library page.

Here's a preview:

Summary of changes:

Redid & pruned some bazel rules to get multiple outputs.
Adjusted the daml-doc RST renderer output to support cross-reference links.
Added a module index that just lists all the modules. This is also used to generate the navigation (automatically) in RST docs.
Added an --index-template option to daml-docs, so you can have a separate template for the module index and individual modules. This was used to make the "standard library" page.
Small annotation changes in the standard library to hide modules that should be hidden, and move other modules to the correct place.

TODO before merging:

Fix hoogle database URLs.

This change also highlights how a lot of our standard library documentation could be improved. Most modules don't yet have any description. Also, it might be better to put data types before typeclasses in each module doc. I will leave further documentation changes to a separate PR.

Pull Request Checklist

Read and understand the contribution guidelines
Include appropriate tests
Set a descriptive title and thorough description
Add a reference to the issue this PR will solve, if appropriate
Include changelog additions in one or more commit message bodies between the CHANGELOG_BEGIN and CHANGELOG_END tags
Normal production system change, include purpose of change in description

NOTE: CI is not automatically run on non-members pull-requests for security
reasons. The reviewer will have to comment with /AzurePipelines run to
trigger the build.

cocreature

Awesome, thanks! Do we need a redirect from the old docs url or does that just point to the main docs page that lists all modules?

compiler/damlc/base-rst-index-template.rst

cocreature · 2020-04-20T16:46:12Z

compiler/damlc/daml-prim-src/LibraryModules.daml

@@ -5,7 +5,7 @@
 {-# OPTIONS_GHC -fno-warn-unused-imports #-}


-- Remove this module when DEL-6311 is done.
+-- | HIDE Remove this module when DEL-6311 is done.


Gotta love comments that refer to jira tickets that have been fixed.

Can't we just remove this file?

Thinking about it, we fixed this for damlc build but we use damlc compile to compile daml-stdlib so it doesn’t help.

Probably ... I'm going to go through the stdlib in a separate PR to clean up docs and I'll try removing it then.

cocreature · 2020-04-20T16:48:17Z

compiler/damlc/daml-stdlib-src/DA/Internal/Compatible.daml

@@ -4,7 +4,7 @@
 {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE PatternSynonyms #-}

-- | Our Prelude, extending WiredIn with things that don't need special treatment.
+-- | HIDE Our Prelude, extending WiredIn with things that don't need special treatment.


This comment doesn’t make sense to me.

compiler/damlc/daml-stdlib-src/DA/Generics.daml

sofiafaro-da · 2020-04-21T08:48:18Z

Awesome, thanks! Do we need a redirect from the old docs url or does that just point to the main docs page that lists all modules?

That sounds like a good idea, I'll add that.

sofiafaro-da · 2020-04-21T10:59:18Z

I made some more changes:

Moved the standard library to daml/stdlib (instead of daml/reference/base), which reflects where it actually is in the docs (there's a whole history here that I don't want to get into ... but suffice it to say that this is where the standard library docs should have been before this PR, but weren't, but there's no longer a reason to have it this way).
Updated the existing standard library redirects, and added a redirect from daml/reference/base.html to daml/stdlib/index.html.
Changed the way modules are listed ... I removed the Module prefix from the index / navigation because I think it looked a bit goofy.
Updated the live preview script.
Updated the hoogle base URL, the URL for generated Hoogle links, and the builtin damlBaseURL used for external links to the standard library. This is a little bit better than pointing to an old page, but it's still not correct in general, especially for Hoogle. The problem is that the way Hoogle is generated right now isn't very amenable to putting in the correct links.
Updated the tests.

If possible, I'll work on improving the Hoogle database in a separate PR. I don't want to make this one any larger than it already is... (Right now the behavior is that if you click on a hoogle link, it will take you to the standard library index instead of the exact module you want. That was only fine when everything was on the same page.)

hurryabit

The output looks great. Thank you so much!

changelog_begin - [DAML Docs] The standard library docs have been split up per module. changelog_end

Co-Authored-By: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

sofiafaro-da requested a review from cocreature April 20, 2020 15:48

sofiafaro-da requested review from bame-da, hurryabit and nemanja-da as code owners April 20, 2020 15:48

cocreature approved these changes Apr 20, 2020

View reviewed changes

hurryabit reviewed Apr 21, 2020

View reviewed changes

sofiafaro-da force-pushed the stdlib-docs branch from 47fe5b0 to 74f8117 Compare April 21, 2020 15:45

sofiafaro-da closed this Apr 22, 2020

sofiafaro-da reopened this Apr 22, 2020

sofiafaro-da force-pushed the stdlib-docs branch from 74f8117 to 1a4ccd4 Compare April 22, 2020 10:32

sofiafaro-da and others added 7 commits April 22, 2020 13:09

One module per page in stdlib docs.

29af72c

changelog_begin - [DAML Docs] The standard library docs have been split up per module. changelog_end

Adjust stdlib annotations

8027b75

Update compiler/damlc/daml-stdlib-src/DA/Generics.daml

0b60cde

Co-Authored-By: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

Update compiler/damlc/base-rst-index-template.rst

9869e24

Co-Authored-By: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

Move to daml/stdlib

a73e7b4

Update daml-doc tests

e703744

Remove the Module prefix in the index/toctree

8d476e4

sofiafaro-da force-pushed the stdlib-docs branch from 1a4ccd4 to 8d476e4 Compare April 22, 2020 12:09

sofiafaro-da merged commit ab93435 into master Apr 22, 2020

sofiafaro-da deleted the stdlib-docs branch April 22, 2020 12:23

jberthold-da mentioned this pull request May 20, 2020

damlc docs generates wrong links for Types from stdlib #6039

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Split standard library docs up one page per module. #5636

Split standard library docs up one page per module. #5636

sofiafaro-da commented Apr 20, 2020 •

edited

Loading

cocreature left a comment

cocreature Apr 20, 2020

hurryabit Apr 21, 2020

cocreature Apr 21, 2020

sofiafaro-da Apr 21, 2020

cocreature Apr 20, 2020

sofiafaro-da commented Apr 21, 2020

sofiafaro-da commented Apr 21, 2020 •

edited

Loading

hurryabit left a comment

Split standard library docs up one page per module. #5636

Split standard library docs up one page per module. #5636

Conversation

sofiafaro-da commented Apr 20, 2020 • edited Loading

Pull Request Checklist

cocreature left a comment

Choose a reason for hiding this comment

cocreature Apr 20, 2020

Choose a reason for hiding this comment

hurryabit Apr 21, 2020

Choose a reason for hiding this comment

cocreature Apr 21, 2020

Choose a reason for hiding this comment

sofiafaro-da Apr 21, 2020

Choose a reason for hiding this comment

cocreature Apr 20, 2020

Choose a reason for hiding this comment

sofiafaro-da commented Apr 21, 2020

sofiafaro-da commented Apr 21, 2020 • edited Loading

hurryabit left a comment

Choose a reason for hiding this comment

sofiafaro-da commented Apr 20, 2020 •

edited

Loading

sofiafaro-da commented Apr 21, 2020 •

edited

Loading