Ivadomed: Reference global variables in RTD

[charleygros]

We have global variables in our code that we would like to reference in the RTD. Is there a way to do this? otherwise, what would be a better practice to handle this?

Issue related to this comment.

[Drulex]

This project uses a mix of md and rst files to build the doc. By design markdown does not have a native way to cross-reference other local markdown files, but reStructuredText has the :ref: directive more info here.

With that said, the project also uses the recommonmark parser which allows to use both rst and md files and provides extra capabilities such as internal link support info here. The project further uses AutoStructify to convert the md documentation to rst (internal linking capability is thus provided by rst).

Now it seems to me that there is a lot of complexity in how the documentation is written. Writing rst everywhere seems simpler than mixing md and rst, however it isn't necessarily bad or forbidden. Based on the recommonmark documentation, internal linking (cross-referencing) should be supported, but I was never able to get it to work (spent at least 45m trying).

@charleygros had the right idea, but should reference local html instead of external html. For example in the context of #281 both of these will work.

- `name`: Name of the [loss function Class](./api_ref.html#ivadomed-losses).
- `name`: Name of the [loss function Class](api_ref.html#ivadomed-losses).

This however is not "real" cross-reference support, but more of a hack using external linking to point to a local html file section (still works in this case though).

To be "clean" it would be better to use proper internal cross-references. Someone could give the recommonmark syntax a try and maybe have better luck than me. Another potential solution is to simplify the whole thing and use rst everywhere.

I suggest to use the html referencing since the use cases seem simple.

[charleygros]

Solution implemented in #274 --> many thanks @Drulex for your investigations & explanations!

[jcohenadad]

With that said, the project also uses the recommonmark parser which allows to use both rst and md files and provides extra capabilities such as internal link support info here. The project further uses AutoStructify to convert the md documentation to rst (internal linking capability is thus provided by rst).

yes... i've learned my lesson the hard way. Started off with full md, and along the way realized the limitations bits by bits, and converted to rst each time i realized recommonmark did not provide the solution. So we end up with this hybrid doc. At this point i agree making it an rst-only doc will be simpler 😅
issue opened here: https://github.com/neuropoly/ivado-medical-imaging/issues/286

[Drulex]

Update since the docs have been updated to use full rst:

We can reference python objects directly using the python domain cross-reference syntax (see https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain)

In this context of #281, the syntax to point to the losses module is the following:

- ``name``: Name of the loss function class. See :mod:`ivadomed.losses`

Which will link to the API documentation. From there there is also a "source" link to view the source code file directly:

[Drulex]

See solution in thread above (https://github.com/ivadomed/ivadomed/issues/280#issuecomment-645452483).

Can we close @charleygros?