documentationgeneratorregistry's Introduction

DocumentationGeneratorRegistry

This registry allows package authors to specify where to find and how to build the documentation for their packages displayed on e.g. juliahub.com.

Usage

Just add a new entry to Registry.toml by hand following the Specifications below (order doesn't matter) or with the provided add_to_registry.jl script:

julia add_to_registry.jl Package1 Package2 Package3

Options

There are three options for specifying how (with the method key) and where (with the location key) to find a package's documentation:

vendored: The documentation source is located in a folder (specified by location) in the package's root directory.
git-repo: The documentation source is located in the git repo given by location.
hosted: The built documentation is reachable under the URL given by location.

Specifications

Each package is specified by UUID, which is also the top-level key. Required sub-keys are method, location, and name:

[uuid]
name = "PackageName"
method = "hosted"
location = "https://thisismy.hosted.documentation.org/stable"

documentationgeneratorregistry's People

Contributors

Stargazers

Watchers

documentationgeneratorregistry's Issues

TOML format design

Current design:

[packages]
e5e0dc1b-0480-54bc-9374-aad01c23163d = { name = "Juno", method = "hosted", location = "https://docs.junolab.org/latest" }

I feel like I've become a nearly full time TOML file format designer, but here goes. The [packages] header seems unnecessary. It exists in the registry Registry.toml file because there's a bit of other metadata you need to know about a registry (originally they were in separate files, but I decided to put the package map in the same file as the registry metadata). I also think the stanza structure could be a bit different. Here are some sketches.

Here's a version using the UUID as a unique key:

[e5e0dc1b-0480-54bc-9374-aad01c23163d]
name = "Juno" # do we need this? I guess it's good to know in any case
method = "hosted"
location = "https://docs.junolab.org/latest"

[fcda24af-3677-4fa2-84a6-1f1efb146dee]
name = "SomePackage"
method = "git-repo"
location = "https://github.com/SomeOrg/SomePackage.jl.git"

If we want to support registering multiple hosting methods (do we?) then we could allow an array of stanzas per UUID, e.g.:

[[e5e0dc1b-0480-54bc-9374-aad01c23163d]]
name = "Juno"
method = "hosted"
location = "https://docs.junolab.org/latest"

[[e5e0dc1b-0480-54bc-9374-aad01c23163d]]
name = "Juno"
method = "git-repo"
location = "https://github.com/JunoLab/Juno.jl.git"

If we're going to allow multiple entries, it might be more readable to use the name as the key like we do in manifest files, e.g.:

[[Juno]]
uuid = "e5e0dc1b-0480-54bc-9374-aad01c23163d"
method = "hosted"
location = "https://docs.junolab.org/latest"

[[Juno]]
uuid = "e5e0dc1b-0480-54bc-9374-aad01c23163d"
method = "git-repo"
location = "https://github.com/JunoLab/Juno.jl.git"

[[SomePackage]]
uuid = "cda24af-3677-4fa2-84a6-1f1efb146dee"
method = "git-repo"
location = "https://github.com/SomeOrg/SomePackage.jl.git"

Recommend Projects

juliadocs / documentationgeneratorregistry Goto Github PK

documentationgeneratorregistry's Introduction

DocumentationGeneratorRegistry

Usage

Options

Specifications

documentationgeneratorregistry's People

Contributors

Stargazers

Watchers

Forkers

documentationgeneratorregistry's Issues

TOML format design

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent