Differences between revisions 1 and 2
Revision 1 as of 2009-02-11 11:22:20
Size: 1233
Editor: EnricoZini
Comment: Started the page
Revision 2 as of 2009-02-11 11:53:00
Size: 3971
Editor: EnricoZini
Comment: Added bit about documentation
Deletions are marked like this. Additions are marked like this.
Line 16: Line 16:
foo: bar
baz:
 gnu: 42
 gnat: also 42
build:
 buildd: http://buildd.debian.org/pkg.cgi?maint=$USER@debian.org
 igloo: http://oldpeople.debian.org/~igloo/status.php?email=$USER%40debian.org&thin=on
 svnbuildstat: http://svnbuildstat.debian.net/packages/list/$USER@debian.org
qa:
 lintian: http://lintian.debian.org/maintainer/$USER@debian.org.html
 lintianfull: http://lintian.debian.org/full/$USER@debian.org.html
 dehs: http://dehs.alioth.debian.org/report.php?login=$USER@debian.org
 debtags: http://debtags.alioth.debian.org/todo.html?maint=$USER@debian.org
membership:
 db: http://db.debian.org/search.cgi?uid=$USER&dosearch=Search
 alioth: http://alioth.debian.org/users/$USER/
Line 25: Line 33:
You can put any file in yaml, json or pickle format, with extension ".yaml", ".json" or ".pickle" accordingly. You can put any file in yaml, json or pickle format, with extension {{{.yaml}}}, {{{.json}}} or {{{.pickle}}} accordingly.
Line 33: Line 41:
The content of the file can be any arbitrary combination of dictionaries, lists or scalars. Branches of a dictionary automatically create subnodes, so that only parts of the dictionary can be accessed.

Line 35: Line 46:
DDE likes to describe the data that it contains, and you can help it.

To document the meaning of a directory under {{{~/.dde}}}, create a {{{.doc}}} file inside it containing normal UTF-8 text.

To document the contents of a data file, create another file with extension {{{.doc.[FORMAT]}}} next to your normal data file. The file should contain a data structure with the documentation of every node, for example:

{{{
cat > ~/.dde/sandbox/$USER.doc.yaml <<EOT
".": Information about $USER@debian.org
build:
 ".": Pages with build status of packages
 buildd: link to buildd.debian.org


  Co-maintainers are not listed
 igloo: link to igloo's buildd statistics
 svnbuildstat: link to svn build statistics
qa:
 ".": Quality Assurance pages
 lintian: Lintian reports
 lintianfull: Full Lintian reports, including "info"-level messages
 dehs: Debian External Health Status
 debtags: Debtags QA page
membership:
 db: db.debian.org user information
 alioth: alioth user page
EOT
}}}

There are two special node names:
 * {{{"."}}} documents the current node
 * {{{"*"}}} documents all child nodes for which no specific documentation has been found

There is only one convention for the contents of the documentation:
 1. One line with short description
 2. (one empty line)
 3. Long description as you please

Documentation is optional, but will greatly help people to understand the data that you are publishing.

Line 36: Line 88:

 * If more users publish data in the same location, the first one that does it gets published, and the others are ignored. Have a look at http://dde.debian.net/dde before publishing to choose a meaningful spot.
 * Please put the software that you use to generate the data online somewhere, and document its location in DDE: this will allow other people to review your software, or to keep maintaining it in case you don't have time anymore.

[:DebianWiki/EditorGuide#translation:Translation(s)]: none

(!) [:/Discussion:Discussion]


This page describes a simple way to publish data files using ["DDE"].

In short

On merkel:

mkdir -p ~/.dde/sandbox
cat > ~/.dde/sandbox/$USER.yaml <<EOT
build:
 buildd: http://buildd.debian.org/pkg.cgi?maint=$USER@debian.org
 igloo: http://oldpeople.debian.org/~igloo/status.php?email=$USER%40debian.org&thin=on
 svnbuildstat: http://svnbuildstat.debian.net/packages/list/$USER@debian.org 
qa:
 lintian: http://lintian.debian.org/maintainer/$USER@debian.org.html
 lintianfull: http://lintian.debian.org/full/$USER@debian.org.html 
 dehs: http://dehs.alioth.debian.org/report.php?login=$USER@debian.org 
 debtags: http://debtags.alioth.debian.org/todo.html?maint=$USER@debian.org
membership:
 db: http://db.debian.org/search.cgi?uid=$USER&dosearch=Search
 alioth: http://alioth.debian.org/users/$USER/ 
EOT

After some time, a cron job will notice the file and tell DDE to publish its contents.

You can put any file in yaml, json or pickle format, with extension .yaml, .json or .pickle accordingly.

You can organise file names and directories as you see fit, for example:

Data file

Is published at

foo.yaml

http://dde.debian.net/dde/q/foo

dir/foo.json

http://dde.debian.net/dde/q/dir/foo

The content of the file can be any arbitrary combination of dictionaries, lists or scalars. Branches of a dictionary automatically create subnodes, so that only parts of the dictionary can be accessed.

Adding documentation

DDE likes to describe the data that it contains, and you can help it.

To document the meaning of a directory under ~/.dde, create a .doc file inside it containing normal UTF-8 text.

To document the contents of a data file, create another file with extension .doc.[FORMAT] next to your normal data file. The file should contain a data structure with the documentation of every node, for example:

cat > ~/.dde/sandbox/$USER.doc.yaml <<EOT
".": Information about $USER@debian.org
build:
 ".": Pages with build status of packages
 buildd: link to buildd.debian.org


  Co-maintainers are not listed
 igloo: link to igloo's buildd statistics
 svnbuildstat: link to svn build statistics
qa:
 ".": Quality Assurance pages
 lintian: Lintian reports
 lintianfull: Full Lintian reports, including "info"-level messages
 dehs: Debian External Health Status
 debtags: Debtags QA page
membership:
 db: db.debian.org user information
 alioth: alioth user page
EOT

There are two special node names:

  • "." documents the current node

  • "*" documents all child nodes for which no specific documentation has been found

There is only one convention for the contents of the documentation:

  1. One line with short description
  2. (one empty line)
  3. Long description as you please

Documentation is optional, but will greatly help people to understand the data that you are publishing.

General guidelines

  • If more users publish data in the same location, the first one that does it gets published, and the others are ignored. Have a look at http://dde.debian.net/dde before publishing to choose a meaningful spot.

  • Please put the software that you use to generate the data online somewhere, and document its location in DDE: this will allow other people to review your software, or to keep maintaining it in case you don't have time anymore.