Provide MyST-compatible output for suggest

[laymonage]

Hey, thanks for the great tool! It's very helpful.

Is your feature request related to a problem? Please describe.

Currently, the suggest command outputs the names in rST format. With the rise of MyST to write Sphinx docs in Markdown, it would be very useful if this tool could also output the suggested names in MyST format.

https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#cross-project-intersphinx-links

Describe the solution you'd like

Provide an argument for suggest to control the output format, e.g. --format, defaulting to --format=rst.

Describe alternatives you've considered

Don't implement it, and let something else convert rST-formatted name to MyST?

Additional context

From a quick look, we probably need to add a method e.g. as_myst in SuperDataObj, similar to as_rst:

sphobjinv/src/sphobjinv/data.py

Lines 226 to 236 in ff9151a

	@property
	def as_rst(self):
	r"""|str| reST reference-like object representation.
	Typically will NOT function as a proper reST reference
	in Sphinx source (e.g., a `role` of
	|cour|\ function\ |/cour| must be referenced using
	|cour|\ \:func\:\ |/cour| for the
	|cour|\ py\ |/cour| domain).
	"""
	return self.rst_fmt.format(**self.as_str.json_dict())

and then maybe add an objects_myst property to Inventory:

sphobjinv/src/sphobjinv/inventory.py

Lines 276 to 291 in ff9151a

	@property
	def objects_rst(self):
	r"""|list| of objects formatted in a |str| reST-like representation.
	The format of each |str| in the |list| is given by
	:class:`data.SuperDataObj.rst_fmt
	<sphobjinv.data.SuperDataObj.rst_fmt>`.
	Returns
	-------
	obj_l
	|list| of |str| -- Inventory object data in reST-like format
	"""
	return [_.as_rst for _ in self.objects]

then add a parameter to suggest() for the format:

sphobjinv/src/sphobjinv/inventory.py

Lines 430 to 438 in ff9151a

	def suggest(self, name, *, thresh=50, with_index=False, with_score=False):
	r"""Suggest objects in the inventory to match a name.
	:meth:`~Inventory.suggest` makes use of
	the edit-distance scoring library |fuzzywuzzy|_
	to identify potential matches to the given `name`
	within the inventory.
	The search is performed over the |list| of |str|
	generated by :meth:`~objects_rst`.

and finally expose that in the parser...

sphobjinv/src/sphobjinv/cli/suggest.py

Lines 41 to 79 in ff9151a

	def do_suggest(inv, params):
	r"""Perform the suggest call and output the results.
	Results are printed one per line.
	If neither |cli:INDEX| nor |cli:SCORE| is specified,
	the results are output without a header.
	If either or both are specified,
	the results are output in a lightweight tabular format.
	If the number of results exceeds
	|cli:SUGGEST_CONFIRM_LENGTH|,
	the user will be queried whether to display
	all of the returned results
	unless |cli:ALL| is specified.
	No |cli:QUIET| option is available here, since
	a silent mode for suggestion output is nonsensical.
	Parameters
	----------
	inv
	|Inventory| -- Inventory object to be output in the format
	indicated by |cli:MODE|.
	params
	|dict| -- Parameters/values mapping from the active subparser
	"""
	with_index = params[PrsConst.INDEX]
	with_score = params[PrsConst.SCORE]
	results = inv.suggest(
	params[PrsConst.SEARCH],
	thresh=params[PrsConst.THRESH],
	with_index=with_index,
	with_score=with_score,
	)

sphobjinv/src/sphobjinv/cli/parser.py

Lines 37 to 38 in ff9151a

	class PrsConst:
	"""Container for CLI parser constants."""

[bskinn]

Thanks, very glad it's been useful to you!

Interesting idea -- MyST is definitely here to stay, and odds are the next time I do anything major in Sphinx, I'll look carefully at doing that work in MyST.

The plan you lay out makes good sense to me, and I can't think of any implementation steps you've missed.

---

The one thing I'll push back on, lightly, is to ask: How valuable is emitting MyST formatting in addition to reST formatting, given that neither the reST currently emitted nor the MyST that'd be implemented for this would actually be a directly-usable cross-reference? (This being because the objects.inv, and thus sphobjinv, works with the long role names, which can't be used in cross-references.)

In other words -- MyST output wouldn't be directly copy-paste usable anyways, so isn't the current reST output good enough?

(That said, see #234, proposing a possible approach to having sphobjinv emit short-form role names, which if it worked should allow both reST and MyST output to be copy-paste usable. It would really be nice if this worked, but I'm a bit nervous that it'd turn out to be a major maintenance headache, trying to keep the directive conversion behavior compatible across Sphinx versions and over time.)