Clarification of Location specification

[mthuurne]

The Location.filename property contains a relative file path, but what is the path separator? I think it would be good to specify that slashes must be used. Should the path start with a separator or not?

Many Python projects are now putting their sources in a src/ directory. Should src/ be part of filename or not? The spec states "relative to the root of a project or source control repository", but those two options can result in different paths. If different tools make different assumptions here, it will hurt interoperability.

For lineno, is the first line of a file considered line 0 or line 1?

For endlineno, is that an inclusive or exclusive bound? I assume inclusive, but it doesn't hurt to be explicit.

Are tools encouraged to fill in endlineno only for multi-line locations, or also for single line locations? A consumer of the data might want to handle known single-line locations differently from locations of which the end point is unknown, so there could be an advantage to filling in endlineno for single-line locations.

[NiklasRosenstein]

Hey @mthuurne!

• Unfortunately I don't think there is a good answer to your question about project roots. I do not want docspec loaders to require an understanding of Git or other VCSs. Requiring relative paths would could also make it difficult to also load external API trees (for example installed modules/packages with docspec-python) because the "root" path may not be shared. docspec-python right now actually does generate only absolute, system-specific paths, which is not exactly what the spec says and maybe it needs to be updated respectively. The loader does not have a concept of the project root, but Pydoc-Markdown does and is happy to consume the docspec API tree with absolute paths.

  I would suggest to add this to the docs:

   fields:
     filename:
       type: str
-      docs: A relative filename (e.g. relative to the project root).
+      docs: The path to the file where the API object owning this location was loaded from. Docspec loaders
+        may not have an understanding of the source code root path without additional configuration, thus it
+        is acceptable to produce absolute system-specific paths by default. Loaders should however support a
+        configuration option to produce POSIX-compatible relative paths for interoperability.

• The first line number of a file is 1, as is the case also in code editors. I will add this to the spec.
• The endlineno is inclusive (so for a single file definition lineno and endlineno can be the same), however the endlineno may be omitted for single-line definitions or if the loader doesn't support the field. Will also add it to the spec 🙂

[mthuurne]

Absolute paths would be fine if the Docspec file is usually produced and consumed on the same machine. Are there situations where you see Docspec files being distributed/published or is it purely a format to pass data between tools inside a workflow?

The directory containing setup.py, setup.cfg and/or pyproject.toml could function as the project base directory. That wouldn't require any knowledge of VCSs. In any case, a relative path isn't meaningful without a base, so I think it would be good to define what that base is, even if relative paths are optional.

For external API trees, I think it would make sense to give each source tree its own Docspec file instead of trying to combine multiple source trees in a single Docspec file.

[NiklasRosenstein]

Hey @mthuurne , so far it was only intended to be used as a file format to pass data between tools (albeit on all the tools I built on top of it so far do not currently rely on the JSON format, but the idea was that you could have for example a Node program yield docspec JSON for a typescript library, etc.)

Specifying exactly what the path can contain implies specifying a lot of other details about the platform and the structure of software repositories/code projects. I would like to avoid that in docspec.