Speed up doc builds & improve documentation #198
Conversation
- Change documentation scope to only public and protected entities - May need to manually document available overloaded interfaces - Reduce MAXRANK from 4 to 3 - Don't generate search index for non-deployed builds - Don't generate graphs for non-deployed builds
Use the Markdown Include functionality to duplicate the workflow, style, License, etc. in FORD "Pages" documentation.
- Links added to existing specs - Some modules are still missing specs
- Try to format some code in such a way that the rendering is OK with GFM and python markdown (FORD)
- Next step: enumerate the missing specs - Then: write missing specs
This commit improves the inline FORD documentation of experimental_error and provides some examples of how to use the FORD linking syntax in the spec.
|
|
||
| ### Description | ||
|
|
||
| Aborts the program with a message and a nonzero exit code. | ||
|
|
||
| ### Syntax | ||
|
|
||
| `call error_stop(msg, code)` | ||
| `call [[stdlib_experimental_error(module):error_stop(interface)]](msg, code)` |
There was a problem hiding this comment.
@jvdp1 I think you were asking about FORD linking syntax. Here (this file) are some examples.
Basically the syntax is put the thing to link to in double square brackets: [[ ]]. There is a left hand side and a right hand side separated by a colon (:), but only the left hand side is needed. e.g., [[stdlib_experimental_error]] and [[stdlib_experimental_error(module)]] would both link to the module page: https://stdlib.fortran-lang.org/module/stdlib_experimental_error.html. The parentheses are used to disambiguate the thing in question because you might have multiple entities of the same name in that scope, e.g., a user defined type and a function of the same name to use as a constructor. Unless there is ambiguity the stuff in parenthesis can be omitted. The right hand side (of the colon), if present will provide the text of the link, and link to the anchor for the RHS entity's entry on the LHS entity's page.
There was a problem hiding this comment.
Thanks @zbeekman for your explanations and example.
|
Thanks for this work! I don't understand the failures --- they seem unrelated to this PR? |
Seems like the canonical/ubuntu website went down or something. I can take a look. |
zbeekman
changed the title
|
There's an issue in the documentation workflow file... debugging. |
zbeekman
changed the title
|
Things should be ready to merge pending review by interested parties. EDIT: NOTE: Documentation build time down to 13s from ~13.5 minutes! (For non-release builds, i.e. PRs.) We could try re-enabling the graphs to see what impact that makes. |
|
Typo fixed, should be ready to merge. I'll leave it here a bit longer in case anyone else has feedback, but feel free to merge if you like. |
|
@zbeekman go ahead and merge it. I think we are all in agreement. Thank you again for your work on this, we all appreciate it. |
The main motivation for this PR is to speed up non-deployment builds which has been accomplished via:
MAXRANKfrom 4 to 3In addition, the documentation was fleshed out & improved, primarily in the FORD "pages" section. I used the markdown include capabilities to duplicate/include the LICENSE, WORKFLOW.md, STYLE_GUIDE.md etc. in the "pages" documentation. I also improved the main index.md "pages" landing page and the "specs" landing page.
Furthermore I edited the
stdlib_experimental_errorspec to illustrate the usage of FORD's linking syntax as requested by @jvdp1. It should be noted that we may want to remove the links from the headings as they break the markdown-toc extension (the TOC does not include a link to the section if the header has a link in it).Finally I prettified and edited the FORD markdown in the implementation of
stdlib_experimental_error.f90a little bit and linked it back to the spec.