remove spaces and line breaks inside urls

[mmatera]

This single line PR is a proposal about how to handle long urls in docstrings. With this patch

<url>:NetworkX:
     https://networkx.org/documentation/networkx-2.8.8/reference/algorithms/\
      generated/networkx.algorithms.tree.mst.minimum_spanning_edges.html
</url>

the tag is processed as

<a href=https://networkx.org/documentation/networkx-2.8.8/reference/algorithms/generated/networkx.algorithms.tree.mst.minimum_spanning_edges.html>NetworkX</a>

The pros are

• we do not need to have long lines in documentation (flake8 complains about it)
• in the code, we can preserve the indentation, and visually looks better.
• we do not need to change the docstrings that were written like this.

The contra is that I don't know if sphinx supports something like that, so it would make the migration harder.

[rocky]

Please put in a comment as to why this is being done.

[rocky]

I am on the fence about this, but in an open-source project if this kind of thing makes you happy or removes an annoyance, and you want to do the work to do this fully then sure, let's go ahead.

So note that a change also needs to be made in doc_utils.py of mathics-core. (In fact in looking over the generated LaTeX file is where I was first alerted something was amiss.)

And readthedocs for what is allowed in a URL tag is also needed.

• we do not need to have long lines in documentation (flake8 complains about it)

flake8 has been told to allow lines up to 300 characters in mathics-core in setup.cfg so that can removed after URL handling allows spaces, if this is done.

• in the code, we can preserve the indentation, and visually looks better.

yes, this is nice.

• we do not need to change the docstrings that were written like this.

This is kind of an unusual argument: I didn't understand how things worked, or test what I did, so instead I'll changed the code to match what thought or hoped it would be.

Personally, I suppose I have done this many times myself too, and there is a kind of benefit: this sometimes is how progress is made. However it is not something, personally, I advertise or tout as an advantage.

The contra is that I don't know if sphinx supports something like that, so it would make the migration harder.

This is an interesting point too. Personally, if I didn't know if sphinx supported something, I would look. And if it doesn't I'd ask myself if not then why not? Or if it handles it but in a different way, then I might try to match that rather than go invent a new convention on my own.

Here is situation with Sphinx: docs can live outside of Python code so it is not subject to pylint style. RsT reflows automatically, and you can use long lines.

Redoing everything for Sphinx is indeed going to cause its own challenge. Not unlike the kind we have seen already. However, in my opinion having good docs now is a sad conscious choice I've made.

Cutting over to Sphinx, even forgetting the markup is such a challenge and lower priority than all of those other major problems we have.

[mmatera]

I am on the fence about this, but in an open-source project if this kind of thing makes you happy or removes an annoyance, and you want to do the work to do this fully then sure, let's go ahead.

I open this to discuss if this solution could work. The other way around would be to reinforce the format of the ... tags in the consistency tests.

So note that a change also needs to be made in doc_utils.py of mathics-core. (In fact in looking over the generated LaTeX file is where I was first alerted something was amiss.)

And readthedocs for what is allowed in a URL tag is also needed.

Yes, I am aware of that, and if we decide that this is an acceptable solution, then I am going to put it in the corresponding PRs.

• we do not need to have long lines in documentation (flake8 complains about it)

flake8 has been told to allow lines up to 300 characters in mathics-core in setup.cfg so that can removed after URL handling allows spaces, if this is done.

OK.

• in the code, we can preserve the indentation, and visually looks better.

yes, this is nice.

• we do not need to change the docstrings that were written like this.

This is kind of an unusual argument: I didn't understand how things worked, or test what I did, so instead I'll changed the code to match what thought or hoped it would be.

Again, the other possibility would be to reinforce the docstrings with a test, and fix all the failing cases. At this point, I guess both options would take more or less the same time to be done.

Personally, I suppose I have done this many times myself too, and there is a kind of benefit: this sometimes is how progress is made. However it is not something, personally, I advertise or tout as an advantage.

The contra is that I don't know if sphinx supports something like that, so it would make the migration harder.

This is an interesting point too. Personally, if I didn't know if sphinx supported something, I would look. And if it doesn't I'd ask myself if not then why not? Or if it handles it but in a different way, then I might try to match that rather than go invent a new convention on my own.

The problem with this is that is actually a question for the future: probably at least until the next year we are going to conserve the present documentation format, just because migrating it would take a lot of time, which I have only during hollidays. So, if we think it is useful, sphinx does not support it, we could ask to the developers. But first, we should agree that it is indeed a good idea.

Here is situation with Sphinx: docs can live outside of Python code so it is not subject to pylint style. RsT reflows automatically, and you can use long lines.

Redoing everything for Sphinx is indeed going to cause its own challenge. Not unlike the kind we have seen already. However, in my opinion having good docs now is a sad conscious choice I've made.

Cutting over to Sphinx, even forgetting the markup is such a challenge and lower priority than all of those other major problems we have.

[rocky]

@mmatera Looks like for this PR, I don't see anything more to do.

If you are up to changing mathics-core and readthedocs to bring them in line with this change. The please go ahead and merge this into master when you are satisfied. And then, at least in the short term (which who knows may be years), is s win.