Clarify error about taken port in serve; allow to open a browser

[oprypin]

• Add a flag to override the serve port
• Add diagnostics when mkdocs serve fails to bind a port

• Closes With mkdocs serve switch to another port if the current port is busy #3496

[oprypin]

I dropped port randomization and trying multiple ports, compared to #3497. I think it can actually be too confusing.

[squidfunk]

So, please don't get me wrong, but IMHO, this is not a very consistent design. You can specify a port via --dev-addr, but also via --port? That's two ways of achieving the same thing.

[oprypin]

OK what do you suggest?

[squidfunk]

Either remove --port or deprecate and split up --dev-addr into --host and --port. I'm not sure what you're aiming here for however, because --dev-addr is working perfectly fine.

[squidfunk]

Also note that all of this might incentivize people to use the development server as a production server, because now you can only set the --port. --dev-addr carries dev in it, which I think was put there deliberately to keep people from using it in production. Still happens more often than one might think, as judging from issues I answered in the past.

[pawamoy]

I would find a -p option really convenient. I literally never change the default host, and if I had to, it would probably be in a container setup where I would set it to 0.0.0.0 and never change it again. Whereas in (rare) cases where I serve multiple sites, I need to change the port, and having to re-specify the default localhost is a bit annoying.

So I wouldn't mind if --dev-addr was deprecated in favor of two --host and --port options. However I'm not the only MkDocs user and I fear it would be quite disruptive to deprecate --dev-addr for, again, rarely happening situations. Maybe they could both (dev-addr and host+port) live together, forever, as mutually exclusive options? Or maybe --dev-addr could be modified so that we can pass either HOST:PORT, or just HOST, or just PORT? It looks like it's easy to distinguish the three cases?

[pawamoy]

What happens if I permanently set the port to 8010 with serve_port: 8010 in the config file, and this port is already in use when I run mkdocs serve? Will I be able to override it with -p 8020 or -a 127.0.0.1:8020?

[pawamoy]

I wonder if this really brings value. Choosing a different ports among different projects will be cumbersome, and will not play well with project templates. Also it caters to a (I'd say) small fraction of users who run multiple live-reload servers concurrently. And IMO is only useful when you also use -o to automatically open the tab in the browser. So many users will likely keep using 8000 by default. Besides, even if you permanently sets ports 8007, 8020, 8055 and 8080 on your projects, nothing guarantees that other projects you contribute to won't use the same ports. In that case you'll again fall back to overriding with -p. The first few ports (and the multiples of 10) will probably be over-used across all projects.

I feel like anything more than a default port plus a way to override it doesn't bring any real guarantee or benefit, and only increases cognitive overhead and/or maintenance work. I do note that this is an opt-in feature, so I won't push against it.

[oprypin]

Yea the feature kinda falls apart easily. A compromise where nobody will bother trying to benefit from it

[squidfunk]

I wonder if this really brings value.

I feel that we're wasting our time discussing something that provides so little value as opposed to other open issues that would need more attention. This won't add any new functionality besides what's already achievable.

[oprypin]

For you perhaps time is money. And for me, not spending time on one interesting issue doesn't mean I'll be more likely to spend time on another issue (actually often quite the opposite)

[fralau]

For you perhaps time is money. And for me, not spending time on one interesting issue doesn't mean I'll be more likely to spend time on another issue (actually often quite the opposite)

That's a key point 🙂, for occasional or volunteer contributors. Both viewpoints exist and complement each other.

Of course, I am beating the drum for my own subjects of interest; though I can see and appreciate the other person's viewpoint.

I any case ifmkdocs could assume that the default host was localhost (mkdocs serve -a 8001), I would consider myself completely vindicated.