6

I've got a lotta docs written in reST (note docs, not docstrings in code) to which I'd like to add (depending on the work) one or more of

  • copyright notice
  • license notice
  • license badge/icon

I'd like to know, are there established conventions for this? Particularly:

I'm guessing this will involve adding to the doc(s) one or more reST directives, and furthermore probably

  1. a meta directive with one or more fields for the copyright notice, license name, license URI, etc
  2. (if badging) an image directive with a field containing the standard URI for the license

If those assumptions are correct, my question becomes: are there canonical fieldnames for each of these data? If not in reST/docutils, are there fieldnames in {canonical, accepted, wide} use in a related domain, like a reST extension (e.g., Sphinx) or a related markup (e.g., Markdown)?

2

RST supports comments in various forms, which could be used to specify licenses inline. This would be similar to adding a license block to an individual source code file in a program.

However.

If you are asking about something like a directory/subdirectory or a whole source code repository (e.g. a Github repo) with documentation, I personally would look for a file called LICENSE or similar in that directory/repository. Failing that I would open the starting page of the documentation and try to figure out where the license is mentioned. Honestly I haven't even considered up to now to try to look for a license block in the documentation source.

Github for example supports extracting the license name out of a LICENSE file, I don't know if it is also able to do that with source code comments especially in a markdown language.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.