Skip to content

Provide a way to compile and link to non-README documentation files #1096

Open
@nex3

Description

@nex3

Here's my use case: I'm working on test, and the documentation is bigger than a single README file. I've already got JSON reporter protocol docs, and I'm planning to add documentation for the configuration file format pretty soon. I want the following things:

  • I want this documentation to be easily consumable on dartdocs.org.
  • I want it to also be easily consumable on GitHub.
  • At least on dartdocs.org, I want it to be versioned—that is, if a user is looking at the dartdocs for version 0.12.10, they see version 0.12.10 of the README and the JSON reporter protocol as well.

There's not a great way to do this right now. There's no way to get dartdoc to compile any pure-Markdown documentation other than the README, and GitHub isn't versioned at all.

I propose the following solution:

  • Crawl the README for links to other documents ending in .md. This should naturally support relative URLs, but it should also support links of the form https://github.com/____/${package}/blob/____/${path}.md.
  • For each link, check for the corresponding path in the package. If it exists, compile it as Markdown and include it in the dartdoc output.
  • Update the links to point to the dartdoc-compiled pages rather than their original destinations.

This would allow users to write multi-page documentation that Dartdoc supports properly, while still linking to the GitHub versions of those docs for GitHub users.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2A bug or feature request we're likely to work ontype-enhancementA request for a change that isn't a bug

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions