Fix broken links in documentation

[dalonsoa]

• If a link to an external website fails because that website is not working, it might be just a glitch and it will work again at some point or it might be truly that the URL to the external website is no longer correct. Then is a problem in MUSE documentation and that link should be updated. For example https://www.anaconda.com/what-is-anaconda/ really does not exist and needs to be updated. Also, for papers you should use proper DOIs rather than URLs, so https://www.sciencedirect.com/science/article/pii/S0306261920308072 should be included as https://doi.org/10.1016/j.apenergy.2020.115295, which is guaranteed to exist (by the definition of DOI, as far as I can tell).
• The internal links are also related to locations that do not exist. For example, if you go to https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.YearlyAggregate, it indeed open the page, but does not go to the tag #muse.outputs.YearlyAggregate, as required, because that tag does not exist. What does exist is #muse.outputs.sinks.YearlyAggregate. I guess that at some point the location of that class was changed, but the documentation was not. And the same with the others.

So, I don't see why they should not be flagged as errors.

Unindented lines indicate the document in which the broken link is found:

*** INFO: [2023-05-26 09:19:31] Start checking: "https://muse-os.readthedocs.io/en/latest/"
[7](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:8)
https://muse-os.readthedocs.io/en/latest/api.html
[8](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:9)
	id #id4 not found	https://muse-os.readthedocs.io/en/latest/api.html#id4
[9](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:10)
	id #intflag not found	https://docs.python.org/3/library/enum.html#intflag
[10](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:11)
	parse ":https://docs.python.org/3/library/abc.html": missing protocol scheme	:https://docs.python.org/3/library/abc.html
[11](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:12)
	parse ":https://www.python-course.eu/python3_abstract_classes.php": missing protocol scheme	:https://www.python-course.eu/python3_abstract_classes.php
[12](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:13)
https://muse-os.readthedocs.io/en/latest/user-guide/addition-service-demand.html
[13](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:14)
	404	https://github.com/SGIModel/MUSE_OS/blob/main/docs/tutorial-code/5-add-service-demand/1-exogenous-demand/technodata/preset/Residential2050Consumption.csv
[14](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:15)
https://muse-os.readthedocs.io/en/latest/overview.html
[15](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:16)
	403	https://www.sciencedirect.com/science/article/pii/S0306261920308072
[16](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:17)
	403	https://www.sciencedirect.com/science/article/pii/S036054421930177X
[17](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:18)
https://muse-os.readthedocs.io/en/latest/advanced-guide/api.html
[18](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:19)
	id #id4 not found	https://muse-os.readthedocs.io/en/latest/advanced-guide/api.html#id4
[19](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:20)
	id #intflag not found	https://docs.python.org/3/library/enum.html#intflag
[20](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:21)
	parse ":https://docs.python.org/3/library/abc.html": missing protocol scheme	:https://docs.python.org/3/library/abc.html
[21](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:22)
	parse ":https://www.python-course.eu/python3_abstract_classes.php": missing protocol scheme	:https://www.python-course.eu/python3_abstract_classes.php
[22](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:23)
https://muse-os.readthedocs.io/en/latest/source/muse.sectors.html
[23](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:24)
	parse ":https://docs.python.org/3/library/abc.html": missing protocol scheme	:https://docs.python.org/3/library/abc.html
[24](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:25)
	parse ":https://www.python-course.eu/python3_abstract_classes.php": missing protocol scheme	:https://www.python-course.eu/python3_abstract_classes.php
[25](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:26)
https://muse-os.readthedocs.io/en/latest/inputs/technodata.html
[26](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:27)
	id #id1 not found	https://muse-os.readthedocs.io/en/latest/inputs/technodata.html#id1
[27](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:28)
https://muse-os.readthedocs.io/en/latest/installing-muse.html
[28](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:29)
	404	https://www.anaconda.com/what-is-anaconda/
[29](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:30)
	id #build-tools-for-visual-studio-2019 not found	https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019
[30](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:31)
	id #download-section not found	https://www.anaconda.com/distribution/#download-section
[31](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:32)
	id #write-a-python-program-using-anaconda-prompt-or-terminal not found	https://docs.anaconda.com/anaconda/user-guide/getting-started/#write-a-python-program-using-anaconda-prompt-or-terminal
[32](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:33)
https://muse-os.readthedocs.io/en/latest/_modules/muse/outputs/sinks.html
[33](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:34)
	id #muse.outputs.FiniteResourceException not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.FiniteResourceException
[34](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:35)
	id #muse.outputs.YearlyAggregate not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.YearlyAggregate
[35](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:36)
	id #muse.outputs.factory not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.factory
[36](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:37)
	id #muse.outputs.finite_resource_logger not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.finite_resource_logger
[37](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:38)
	id #muse.outputs.sink_to_file not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.sink_to_file
[38](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:39)
	id #muse.outputs.standardize_quantity not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.standardize_quantity
[39](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:40)
	id #muse.outputs.to_csv not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.to_csv
[40](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:41)
	id #muse.outputs.to_excel not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.to_excel
[41](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:42)
	id #muse.outputs.to_netcdf not found	https://muse-os.readthedocs.io/en/latest/source/muse.outputs.html#muse.outputs.to_netcdf
[42](https://github.com/SGIModel/MUSE_OS/actions/runs/5089256100/jobs/9146661478?pr=123#step:3:43)
*** ERROR: [2023-05-26 09:19:45] Something went wrong - see the errors above...

[sgiarols]

OK, if you can make the errors more specific they will be easier to checked. When I tried them, it seemed that in general not all the errors were actually for broken links.

One more point is about this issue I opened
#99
Which is what we discussed, in terms of what checks can we have to understand whether the tutorials reported in the documentation need to be updated?

@dalonsoa please let me know if I should wait for one more update on this issue before checking the documentation.

[dalonsoa]

Could you indicate which links are not really broken links, following my clarifications above?

[sgiarols]

As I check them one by one, I will fix those really broken.
I will do this by the end of next week.

[sgiarols]

@dalonsoa Errors 8-11 and 18-24 are unclear.
Apart from those, remaining points appear real errors only on the online of the documentation. Locally I obtain that the tags from the toc tree are working properly.
Best to quickly discuss how to proceed.

[dalonsoa]

Ok, I've found the issue with some of the unclear broken links.

For example, 8 and 18 is about not finding id4. The problem in this case is that the original docstrings that documentation is building from has the wrong formatting. It looks like:

    """Net present value (NPV) of the relevant technologies.

    The net present value of a Component is the present value  of all the revenues that
    a Component earns over its lifetime minus all the costs of installing and operating
    it. Follows the definition of the `net present cost`_ given by HOMER Energy.
    Metrics are calculated
    .. _net present cost:
        https://www.homerenergy.com/products/pro/docs/3.11/net_present_cost.html

    - energy commodities INPUTS are related to fuel costs
    - ..."""

And it should be:

    """Net present value (NPV) of the relevant technologies.

    The net present value of a Component is the present value  of all the revenues that
    a Component earns over its lifetime minus all the costs of installing and operating
    it. Follows the definition of the `net present cost`_ given by HOMER Energy.
    Metrics are calculated:

    .. _net present cost: https://www.homerenergy.com/products/pro/docs/3.11/net_present_cost.html  # noqa

    - energy commodities INPUTS are related to fuel costs
    - ..."""

I don't know when that wrong formatting has taken place, but to ensure that doesn't happen again bvy mistake, we need to add the # noqa label at the end of the long line, so it is ignored by the reformater.

For 9 and 19, on the other hand, the problem is that the label does not exist anymore in the python documentation. We have:

https://docs.python.org/3/library/enum.html#intflag

And we should have:

https://docs.python.org/3/library/enum.html#enum.IntFlag

For 10, 11, 20, 23, and 24, we just have the URL formatted wrong. We have this:

:https://docs.python.org/3/library/abc.html
:https://www.python-course.eu/python3_abstract_classes.php

And should have this:

https://docs.python.org/3/library/abc.html
https://www.python-course.eu/python3_abstract_classes.php

Notice the starting colon that I have removed.

If you have fixed all the others, with these changes I feel you should be able to get the documentation built without broken links.