RST export: LINKs from requirements and other nodes: Resolve and export them correctly

[haxtibal]

Have you already thought about how to represent inter document links? Say [LINK: A1] in 01.sdoc references [ANCHOR: A1] in 02.sdoc.

I'm afraid it's impossible with native docutils rst syntax. docutils can't handle multiple input rst files. Internal hyperlink targets only work within a single rst file.

Sphinx has the :ref: role for exactly that use case. But that is Sphinx specific... In other words, do you think it would be ok if strictdoc export --formats rst generated Sphinx specific rst syntax?

[stanislaw]

StrictDoc has been using the :ref: syntax already, see tests/integration/commands/export/rst/41_link_to_node/expected/input.rst.

I think it is fine to continue using it because there is no better option. Let's wait until someone really needs it outside Sphinx.

Note that the only reason StrictDoc uses RST as its default markup is because it is better than Markdown but also because implementing a custom markup would have made us spend time on it.

I am personally not a big fan of RST and Sphinx over time. You probably saw this thread, here is a FYI just in case: https://github.com/strictdoc-project/strictdoc/issues/1093.

[haxtibal]

StrictDoc has been using the :ref: syntax already, see tests/integration/commands/export/rst/41_link_to_node/expected/input.rst.

Thanks, I must have been blind. Yes :ref: is already used. More aspects of this issue than I've been aware of were already implemented in RSTWriter.

So preparing a PR was not to hard. It will come soon, have to fix some tests first.

I think it is fine to continue using it because there is no better option. Let's wait until someone really needs it outside Sphinx.

Agreed. Dealing with multiple sdoc/rst (which is the nature of StrictDoc) necessarily gets us to Sphinx. Aiming for native docutils compliance makes no sense.

Note that the only reason StrictDoc uses RST as its default markup is because it is better than Markdown but also because implementing a custom markup would have made us spend time on it.

That's a big reason :)

I am personally not a big fan of RST and Sphinx over time. You probably saw this thread, here is a FYI just in case: #1093.

If you want to share documentation organization wide, share multiple versions of it and have full text search then this means readthedocs. I know no other similar free tool (do you?). readthedocs means Sphinx, that's kind of lock in. Haven't yet checked your reasons in #1093, will do now.

[stanislaw]

I am personally not a big fan of RST and Sphinx over time. You probably saw this thread, here is a FYI just in case: #1093.

If you want to share documentation organization wide, share multiple versions of it and have full text search then this means readthedocs. I know no other similar free tool (do you?). readthedocs means Sphinx, that's kind of lock in. Haven't yet checked your reasons in #1093, will do now.

Just out of curiosity: Are you using a commercial version of readthedocs? Why would you not consider deploying StrictDoc static HTML and have it hosted as a static website?

(EDITED: Are the share multiple versions of it and have full text search only reasons for using readthedocs?)

I am asking simply because for me and @mettta, ideally, StrictDoc would receive more development to its core, not to its RST interface. There are more things that that are doable with StrictDoc static and dynamic UI over time, so always relying on subset of what's possible with RST might be somewhat limiting for our future development.

Just trying to understand your use case better.

[haxtibal]

Just out of curiosity: Are you using a commercial version of readthedocs? Why would you not consider deploying StrictDoc static HTML and have it hosted as a static website?

No, none at all. I intend to try a local installation one day. Actually I have no I idea how hard it will be and what's available with the free version.

• If you click on the v: symbol, you can switch between multiple versions. I hope this is useful not only for multiple released versions, but also when multiple people work on different parts of a document in feature branches, and each wants to share their current draft with others.
• It provides full text search.
• It has a good PDF export (all documents merged to one global document, cross references work).
• Integrates with common git forges.

Are the share multiple versions of it and have full text search only reasons for using readthedocs?

The single global PDF is equally important.

I am asking simply because for me and @mettta, ideally, StrictDoc would receive more development to its core, not to its RST interface. There are more things that that are doable with StrictDoc static and dynamic UI over time, so always relying on subset of what's possible with RST might be somewhat limiting for our future development.

I would be happy to not do a readthedocs evaluation if one can get the listed features more easily. What would be your approach? Sharing the static content on a web server gives none of the above features, does it?

[stanislaw]

Just out of curiosity: Are you using a commercial version of readthedocs? Why would you not consider deploying StrictDoc static HTML and have it hosted as a static website?

No, none at all. I intend to try a local installation one day. Actually I have no I idea how hard it will be and what's available with the free version.

* If you click on the v: symbol, you can switch between multiple versions. I hope this is useful not only for multiple released versions, but also when multiple people work on different parts of a document in feature branches, and each wants to share their current draft with others.

This one is not implemented and not on the roadmap yet but like everything else could be doable. Do you know if readthedocs is Sphinx-only?

* It provides full text search.

Not implemented but I wanted to get it work in both static HTML (Sphinx-like) and dynamic HTML in a more feature-rich way (Confluence-like).

* It has a good PDF export (all documents merged to one global document, cross references work).

We wanted to do a single page export with HTML2PDF. It is as easy as merging multiple SDoc models into one SDoc document in memory and printing it to PDF. It is planned.

* Integrates with common git forges.

Depending on what exactly you mean here, it may be more or less doable.

Are the share multiple versions of it and have full text search only reasons for using readthedocs?

The single global PDF is equally important.

I am asking simply because for me and @mettta, ideally, StrictDoc would receive more development to its core, not to its RST interface. There are more things that that are doable with StrictDoc static and dynamic UI over time, so always relying on subset of what's possible with RST might be somewhat limiting for our future development.

I would be happy to not do a readthedocs evaluation if one can get the listed features more easily. What would be your approach? Sharing the static content on a web server gives none of the above features, does it?

Yes, at the moment your list would require readthedocs/Sphinx if you need this to work right away, so you are probably on the right track with considering readthedocs. I myself only used GitHub and GitLab Pages but AFAIK they don't provide the features from your list.

[haxtibal]

This one is not implemented and not on the roadmap yet but like everything else could be doable. Do you know if readthedocs is Sphinx-only?

The examples and guides I've seen are for Sphinx and MkDocs. Otoh, their project README says "It supports many documentation tools (e.g. Sphinx docs written with reStructuredText, MkDocs docs written with markdown, among others)". So I wonder what "others" are.

Not implemented but I wanted to get it work in both static HTML (Sphinx-like) and dynamic HTML in a more feature-rich way (Confluence-like).

That's interesting. If you have multiple projects in your organization (multiple strictdoc.toml in multiple git repos), could this be combined to an organization wide search index?

We wanted to do a single page export with HTML2PDF. It is as easy as merging multiple SDoc models into one SDoc document in memory and printing it to PDF. It is planned.

This one would be great. I'm probably not yet deep enough into StrictDoc to help.

Depending on what exactly you mean here, it may be more or less doable.

Automatically publish drafts for merge requests, and automatically publish release versions on release. Rtd seems to have more fancy stuff.

Yes, at the moment your list would require readthedocs/Sphinx if you need this to work right away, so you are probably on the right track with considering readthedocs. I myself only used GitHub and GitLab Pages but AFAIK they don't provide the features from your list.

GitLab pages is a candidate for the job. I believe it's not that simple to have draft versions (from merge requests) in parallel to release versions that don' overwrite each other. Do you know how that could work?

[stanislaw]

This one is not implemented and not on the roadmap yet but like everything else could be doable. Do you know if readthedocs is Sphinx-only?

The examples and guides I've seen are for Sphinx and MkDocs. Otoh, their project README says "It supports many documentation tools (e.g. Sphinx docs written with reStructuredText, MkDocs docs written with markdown, among others)". So I wonder what "others" are.

In fact, StrictDoc itself could benefit from being hosted on ReadTheDocs. I am waiting for my next big vacation to accomplish several related things:

• Add a landing page / front website for StrictDoc, hopefully using StrictDoc's own features, i.e., not introducing another engine like Pelican, Hugo, ... The idea here is that StrictDoc would provide a minimalistic capability for creating landing pages customized by a user. Before jumping to the normal SDoc doc tree, you would see the front website with several static pages, describing the project, About, Contact, and other usual stuff. Something like https://bazel.build/ (SDoc front website) and more specific https://bazel.build/release/rule-compatibility (SDoc document).
• Replace the existing Sphinx documentation with the StrictDoc documentation with the front website on top of it.
• Deploy the new website to GitHub pages or Read the Docs, making it a default StrictDoc documentation and removing the Sphinx-based documentation.

Not implemented but I wanted to get it work in both static HTML (Sphinx-like) and dynamic HTML in a more feature-rich way (Confluence-like).

That's interesting. If you have multiple projects in your organization (multiple strictdoc.toml in multiple git repos), could this be combined to an organization wide search index?

This is not implemented, and I was too blocked by other tickets to even consider such a larger-scale, let's call it enterprise-level, feature.

We wanted to do a single page export with HTML2PDF. It is as easy as merging multiple SDoc models into one SDoc document in memory and printing it to PDF. It is planned.

This one would be great. I'm probably not yet deep enough into StrictDoc to help.

This will become my next ticket, I wanted to implement it for quite some time now.

Depending on what exactly you mean here, it may be more or less doable.

Automatically publish drafts for merge requests, and automatically publish release versions on release. Rtd seems to have more fancy stuff.

Yes, doing all of these would make us spend time on competing with Read the Docs or GitHub pages, which is most certainly unreasonable. Instead, StrictDoc should cooperate with other tools that focus on one thing well. I am open to considering any new ideas and approaches here.

Yes, at the moment your list would require readthedocs/Sphinx if you need this to work right away, so you are probably on the right track with considering readthedocs. I myself only used GitHub and GitLab Pages but AFAIK they don't provide the features from your list.

GitLab pages is a candidate for the job. I believe it's not that simple to have draft versions (from merge requests) in parallel to release versions that don' overwrite each other. Do you know how that could work?

This depends on how fancy you want this to work. At my job, we simply access raw folders where all GitLab branches are deployed and you can access both the development branches and the release-tagged folders. Our content is Doxygen-only but very well-documented. It is developer-friendly only but does the job well enough for us at the moment.

I am pretty sure there should be some nicer setups but haven't spent any time looking into the features provided by GitLab.