[fix] dead links in documentation

[kyle-cochran]

Describe the bug From a list compiled by Dhruv Jain

1.  OTSK Core:
1.  https://open-space-collective.github.io/open-space-toolkit-core/html/index.html
1.  Documentation >>Python >> 404
2.  Tutorials >> C++ >> 404
3.  Tutorials >>Python >> 404
4.  Contribution >> Contributing guide >> blank

1.  README
1.  Documentation >> Python >>  “I do not believe the link is landing on the correct page”
2.  Tutorials >> C++ >> empty folder
3.  Tutorials >> Python >> empty folder

[DhruvJ22]

Thank you for making the ticket!

There are three sets of bugs: python documentation, tutorials for c++ and python, and contribution guide link in c++ documentation. I will address each of them in separate comments to delink the discussion of the three.

I do not have a ton of experience with software development, please feel free to challenge my assumptions. Additionally, if the bugs are resolved for Core, then similar patches can be applied for other repos.

[DhruvJ22]

Python documentation:

I believe there is currently no robust documentation mechanism in place that represents the mapping between c++ functions and their python coutnerparts, which in most cases have different names. Will it suffice to leverage "@relates" command to showcase the mapping in the doxygen generated documentation, or is there a need to create an independent and more involved documentation for python counterparts?

[DhruvJ22]

Tutorials:

Q1. Is it of interest to create tutorials for the core functionalities, or is it reasonable to route to the OTSK notebooks? Q2. How is the purpose of tutorials different from documentation for core?

[DhruvJ22]

Contribution guide link in documentaiton: It is a simple fix, the old link needs to be replaced with this link

I would like to try to update this as it seems straightforward to modify.

[kyle-cochran]

Python documentation:

I believe there is currently no robust documentation mechanism in place that represents the mapping between c++ functions and their python coutnerparts, which in most cases have different names. Will it suffice to leverage "@relates" command to showcase the mapping in the doxygen generated documentation, or is there a need to create an independent and more involved documentation for python counterparts?

Hey Dhruv, for this one, I'm not sure if the Doxygen "@relates" command would do the trick. The Python versions of functions are generated on-the-fly at compile-time. From what I understand (although I'm not too familiar with Doxygen, so could be wrong) the name of the related function is needed when writing the doc-string as in the example here.

A known solution, although a pain in the butt, is this one. Pybind has a built-in mechanism for creating Python documentation which uses Sphinx in the backend. Another example here.

The downside is that it requires putting the Python doc-string directly into the declaration for the Python bindings, which just means someone has to go on a heroic copy-paste mission in the OSTk repos. Not exceptionally difficult, we just haven't quite gotten to it yet.

[kyle-cochran]

Tutorials:

Q1. Is it of interest to create tutorials for the core functionalities, or is it reasonable to route to the OTSK notebooks? Q2. How is the purpose of tutorials different from documentation for core?

For this one: A1: It certainly wouldn't hurt to have dedicated tutorials for Core functionalities. However, since most functionality will be used within or alongside thing from OSTk Astrodynamics, the current focus for tutorials is in Astrodynamics. If you've got a notebook/script that you're tinkering with to understand the concepts, feel free to open a merge request that adds it as a tutorial!

A2:

• Tutorial -> a step-by-step guide to accomplish something with the library, with a goal in mind.
• Documentation -> usually just descriptions of the functions/classes, but may contain example usage.

^there's totally some overlap, especially for Core, but this is how we tend to think about it. A more complicated example of a tutorial here might be something like: Create a table of data using the Table class, create an output file using the FileSystem tools, then dumping the table data as CSV.

[DhruvJ22]

Python documentation: I believe there is currently no robust documentation mechanism in place that represents the mapping between c++ functions and their python coutnerparts, which in most cases have different names. Will it suffice to leverage "@relates" command to showcase the mapping in the doxygen generated documentation, or is there a need to create an independent and more involved documentation for python counterparts?

Hey Dhruv, for this one, I'm not sure if the Doxygen "@relates" command would do the trick. The Python versions of functions are generated on-the-fly at compile-time. From what I understand (although I'm not too familiar with Doxygen, so could be wrong) the name of the related function is needed when writing the doc-string as in the example here.

A known solution, although a pain in the butt, is this one. Pybind has a built-in mechanism for creating Python documentation which uses Sphinx in the backend. Another example here.

The downside is that it requires putting the Python doc-string directly into the declaration for the Python bindings, which just means someone has to go on a heroic copy-paste mission in the OSTk repos. Not exceptionally difficult, we just haven't quite gotten to it yet.

I believe Vishwas has implemented, something similar, so I will be happy to use that template for core and other repos.

[DhruvJ22]

Tutorials: Q1. Is it of interest to create tutorials for the core functionalities, or is it reasonable to route to the OTSK notebooks? Q2. How is the purpose of tutorials different from documentation for core?

For this one: A1: It certainly wouldn't hurt to have dedicated tutorials for Core functionalities. However, since most functionality will be used within or alongside thing from OSTk Astrodynamics, the current focus for tutorials is in Astrodynamics. If you've got a notebook/script that you're tinkering with to understand the concepts, feel free to open a merge request that adds it as a tutorial!

A2:

* Tutorial -> a step-by-step guide to accomplish something with the library, with a goal in mind.

* Documentation -> usually just descriptions of the functions/classes, but _may contain example usage_.

^there's totally some overlap, especially for Core, but this is how we tend to think about it. A more complicated example of a tutorial here might be something like: Create a table of data using the Table class, create an output file using the FileSystem tools, then dumping the table data as CSV.

Thanks for the suggestions! I am trying to fix the contribution link and it seems to be tied to the difference between how GitHub and doxygen processes relative links.