janestreet / janestreet/base

search friendly html document by removing <span>s

Open
#104 1 comment 0 reactions 0 assignees View on GitHub
forwarded-to-js-devs
Dominant language
OCaml
Stars
1.1k
Forks
177
PR merge metrics
No merged PRs in 30d

Description

It may be the case for non-expert users to search for a type to check whether some standard function exist,
e.g. I searched `'a -> 'a -> 'a` in the [List module](https://ocaml.janestreet.com/ocaml-core/latest/doc/base/Base/List/index.html) to check how many variants of `List.reduce` and pick one.

However, the current generated HTML doesn't support a naive search of type string like `'a -> 'a -> 'a`. The reason is there are some `` in it to prevent web browser in page search to find it easilly.
```html
('a -> 'a -> 'a)
```

I can search ` 'a -> 'a -> 'a` in the [source code](https://github.com/janestreet/base/blob/master/src/list.mli).

I suggest removing some spans in the output to make it friendly to naive in-page search.

Contributor guide

Open the contributing guide

Research direction

Compare the generated List module HTML with the linked src/list.mli, focusing on the span elements wrapping type signatures and arrows. Trace the documentation-generation entry point that produces this output; done means type strings remain formatted while browser in-page search can find them as plain text.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
documentation, search
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.