Feature ideas and improvements

[lorenzoh]

Feature ideas

• Check that internal links point to valid documents
• Annotate Julia code with syntax highlighting information using CSTParser.jl
• Allow referencing individual symbols from other modules (#PackageDocumentation)
• include source file browser for a package with automatic referencing of symbols
• for each data structure search methodswith for relevant functions that can be used on the data structure
  • this could go some way toward alleviating the issue many Python users have of not being able to do obj.<TAB>

Workflow:

• nbdev-like development workflow. Write library code in Jupyter notebooks and have documentation files and Julia files generated from the notebooks.

Document model:

• Transclude documents into a page. For example, the docstring of a symbol or a code example from elsewhere (latter requires a global id)
• collect tests, run them and build the output into a document
• build dependency graph of package functions

Hosting:

• for pages with code examples, output an additional Pluto.jl file that can be downloaded/opened on Binder with a button
• One-click Colab integration for Jupyter notebook sources

Frontend:

• Table of contents/headings for every open tab, implemented similarly to GitHub READMEs
• close tab button for every tab on top right
• Add per-page comment section, e.g. based on https://utteranc.es/
• Floating header. Nice on long pages when you scroll down a lot.
• Table of contents in tab header. Design similar to GitHub markdown viewer
• more advanced search, e.g. using svelte-spotlight
• better module pages
  • add search to module definitions table
  • display source files in a tree
• add version switcher for docs
• copy button on code blocks

CI:

• make it possible to host multiple versions of the frontend
• add CI action to create new docs version when new version is tagged
• check docs for failures in CI and build a preview

Integration with other packages:

• QuizQuestions.jl for more interactive documentation

Improvements

• use thread-safe dictionary data structure to make use of parallelism and speed up builds
• suffix Formats with Format, e.g. HTMLFormat so they can be exported without name conflicts
• remove documents prefix for source documents
• better interactive reloading
  • watch folder to see when files are added (DocumentFolder)
  • watch the table of contents toc.json and reload it when changed
• better error printing for code cells using Base.showerror

Frontend:

• use newly released dynamic element <svelte:element>