Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initial iteration of documentation generation #6

Merged
merged 12 commits into from
Feb 4, 2020
Merged

Initial iteration of documentation generation #6

merged 12 commits into from
Feb 4, 2020

Conversation

SquidDev
Copy link
Owner

@SquidDev SquidDev commented Jan 31, 2020 •
edited
Loading

Port over our old documentation extraction system to the new processor. This rather needs a rewrite, but all my attempts have ended in failure.

Still to do

  • Work out how to handle library paths, and passing around configuration options for it.
  • Merging modules with duplicate names.
  • Documenting things in the global environment (print, etc...). And being able to cross-reference to them.
  • Allow some level of template customisation (allow markdown and html index contents, custom page title, etc...)
  • Fix references in the index page.
  • Tests

Linting

  • Warn on undocumented nodes
  • Warn on unresolved and malformed references.
  • Warn on detached documentation comments
  • Forward any additional errors from extraction (mismatches and whatnot)
  • Check code examples are well formed? Not sure how we'd do this when accounting for expected outputs.

Do we want to run these linters when running doc-gen too?

@SquidDev SquidDev added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 31, 2020
@SquidDev
Initial iteration of documentation generation
79ad9c0 
 - Replace our custom path library with Fpath. It's rather more sturdy
   than our implementation after all.
 - Port over our old documentation extraction system to the new
   processor. This rather needs a rewrite, but all my attempts have
   ended in failure.
@SquidDev
Add tests for undocumented nodes
085e125
@SquidDev
Linter for unresolved references in doc comments
b39af60
@SquidDev
Allow customising where documentation is emitted too
1d66aac 
Also create the target directory if required.
@SquidDev
Make _ENV resolve to the global table
6e2b074 
This is a really dirty hack to make `_ENV.foo = 123` work the same as
doing `foo = 123`. This is largely useful for CC:T, where APIs do sneaky
things like this.
@SquidDev
Make that styling a little less cramped
00e9e98
@SquidDev
Merge modules together
50f910c 
This allows you to declare "stub" files which define any additional externals.
@SquidDev
Be a bit smarter about methods
6de0f2d 
 - Functions now store if they have an implicit self.
 - When converting a function to a method, check if we have an implicit
   self, or have an explicit self argument (dropping it if so).
@SquidDev
A couple of bug fixes
b9d0853 
 - Remove terms annotated with @Local in a post-processing step
 - Fix the parser recognising strings starting with `---`.
@SquidDev
Add a couple of tests
d0161cb 
Also:

 - Rename "APIs" and "Libraries" to the more general "Globals" and
   "Modules". While there's no pretending illuaminate is designed for
   CC:T, let's not get too suck in its nomenclature.
@SquidDev
Highlight RGB hex colours within markdown
abc7066
@SquidDev SquidDev marked this pull request as ready for review February 4, 2020 15:34
@SquidDev SquidDev merged commit 22e9367 into master Feb 4, 2020
@SquidDev SquidDev deleted the feature/doc-gen-again branch February 4, 2020 16:21
This was referenced Feb 4, 2020
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@SquidDev