-
Notifications
You must be signed in to change notification settings - Fork 88
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
Multipage manual in odoc #479
Comments
I'm not fond of the suggestions you make regarding how to populate the sidebar:
This seems both fairly adhoc, and potentially annoying: what if I'm linking to some page that I don't want to appear there?
Definitely not fond of such a non-local analysis (and it also seems fairly fragile), though I guess it could be done during the "link" step.
There is no semantic notion of folders. Apart from that, notice that it's something we could already do with compilation units, but do not. My personal take on the topic is that, for now, you should structure your "manual" in the same way you structure your API docs: the "landing page" should link you to all the relevant places, and it should always be easy (i.e. there should only be one step) to jump back to that page. |
I also have @voodoos needs, but I concur with @trefis. Note that the language already has things like We could add something like a |
We had a discussion about this sort of issue a few weeks ago during a dev meeting. We came up with a proposal that should help - the draft design doc is on the wiki here: https://github.com/ocaml/odoc/wiki/Document-Tree-model - comments and suggestions would be really helpful! |
@jonludlam I'd need more effective details to form a concrete opinion but I'm a bit skeptical about the proposal:
An example for 1. Suppose I have a tutorial in a |
@dbuenzli With respect to 1, I think that the documentation is already very hierarchically oriented due to the APIs themselves being hierarchical. Allowing this hierarchy to be extended to include the pages as well is I think very natural. Whilst you sometimes want to have non-hierarchical structure, you do sometimes just want the hierarchy (e.g. wanting the main page of a library to contain all the modules in the library). I think that adding the ability to include other items in the table of contents is very reasonable, but when I have a simple hierarchy I would like to get the obvious thing by default without needing to do such customisation. In other words, I think your feature can be considered separately and in addition to the pages proposal. With respect to 2, the flexibility is deliberate. I'm in favour of there being opinionated views on how packages/libraries layout their documentation, but I do not believe that odoc is the place those opinions should live. I originally tried to have a very unopinionated notion of |
Just to make clear I'm not against the proposal, I have now written quite extensive
It's not because APIs are hierarchical, that your high-level documentation should be. On the contrary, it should rather not be and provide meaning across the API hierarchy (and as for the hierarchy in those documents someone recently pointed to me again that the feynman lectures on physics covers all of physics from celestial mechanics to quantum electrodynamics with just two hierarchical levels…).
I think one should be careful with that, arbitrary organisation is not a good thing for end-users, in the end the language and the the way libraries are installed (and maybe in the future namespaced) do already provide organisation system itself and I think it would be wrong to ignore it. One of the virtue of |
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors. An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help. |
Since #61, one can write manuals in odoc by creatings
.mld
files and cross-referencing them.However the left sidebar that contains the table of content will always show only the opened file structure, without links to other pages of the manual.
This makes the discovery of pages of the manual quite difficult as one has to look for links in the text. I think it would be more useful to display in the sidebar, in addition to the detailed outline of the current file, links to the other pages of the manual.
It is not obvious how the list of page-links should be made. It could be established in a number of ways:
.mld
files in the current folder.mld
files in the folder and its subfoldersAnother issue would be the name to display in the side bar. It could be:
{1 ...}
in the fileExample
It could look like that in a three-pages manual :
![image](https://user-images.githubusercontent.com/5031221/91866010-4f5ad080-ec72-11ea-96c3-9bf95863bf18.png)
Where "Emacs reference" and "Vim reference" are not headers of the main page but links to two other pages of the manual named
Emacs reference.mld
andVim reference.mld
.The text was updated successfully, but these errors were encountered: