raku / documentable Goto Github PK

This sentence in the README.md needs an OR.

This issue comes from Raku/doc#1912 and it's also present here.

Some pages are generated always:

language.html
routine-method.html
routine-operator.html
routine-sub.html
routine-submethod.html
routine-term.html
routine-trait.html
routine.html

Can't they be cached, or simply checked for changes?

If you add a new file, documentable update reports

Checking for changes...
Everything already updated. There are no changes.

So apparently you have to run start all over again when a new file appears.

Pod::To::Cached and this module have been moved to the perl6 organization in GitHub. Please adapt documentation to reflect that.

It would help with this issue Raku/doc#3046 Hacking a JS to substitute it on the client might not probably be a good idea.

JJ:

Index pages were generated by code in the previous version. It should probably use a template.

Antonio:

Mm, this arises some questions:

• What should be included in the template? All pages share a common wrapper, which includes the auto-generated menu (which cannot be hard-coded in the template).
• Each index page shows information in a different format (see language, types and routines index pages), so a specific template for every index page is needed.
• Currently, index pages are generated by code, creating a pod structure (a table with a title and a subtitle). Once it's created, it's converted to html and the common wrapper is added.

JJ:

I guess the common elements plus a placeholder for where the indices should be placed...

Documentable update will simply not do anything if, say, template/footer.html is changed.

You might not want to use them in production.

To avoid future problems with the language name.

Add it.

The command is not detected

Right now, when there's an error, the only option is to do documentable start all over again. There should be some way of doing documentable continue, if it stops due to some error.

If it's used for testing only, it should go into the test directory. If it's used elsewhere, into the resources directory.

The main source for this is Raku/doc#3031, but apparently there are many pages which still have the same problem, by doing git grep over the generated documents in a repo.

Expected behavior

I am not sure if this is due to a failed regeneration of the pages or what. I think that, to be sure, we need to check that those pages are generated correctly.

Note: My upcoming PR should fix the following minor problem.

Describe the bug
Do the following steps in a clean (preferably empty) directory:

$ clone https://github.com/perl6/Documentable.git
$ cd Documentable
$ ls -CFd *
CHANGELOG.md	  LICENSE     Perl6-Documentable.iml  TODO.md  docs/  resources/
Documentable.iml  META6.json  README.md		      bin/     lib/   t/

Notice no "html" directory in the top level (but is does exist in the "resources" directory). Then, still in the Documentable directory:

$ zef install --force-install .
$ ls -CFd *
CHANGELOG.md	  LICENSE     Perl6-Documentable.iml  TODO.md  docs/  lib/	  t/
Documentable.iml  META6.json  README.md		      bin/     html/  resources/

Notice the "html" directory has been copied from the existing "resources" directory into the top level directory. Then, still in the same directory run:

$ documentable setup; documentable clean
$ ls -CFd *
CHANGELOG.md	  LICENSE     Perl6-Documentable.iml  TODO.md  docs/  resources/
Documentable.iml  META6.json  README.md		      bin/     lib/   t/

Notice the "html" directory is now gone again from the top level.

Conclusion
The "html" directory is apparently not needed for the "install" step so it can be eliminated there.

JJ:
There are also other uses of load (as opposed to self.load in Perl6::Documentable::Registry) outside the not-cached code. It's probably better to check them.
The best thing would be, Perl 6 style, to have two different objects (cached or not) or method implementations, so that ifs (and possible bugs) are avoided.

Antonio: Mmm to have two different methods: load-from-cache and load, for instance?

JJ: @antoniogamiz Sorry. I'll have to check this more thoroughly. I think my initial intention was more along the lines of actually caching them, to treat them the same as any other.

This error occurs (apparently) when HomePage.pod6 is updated

No such method 'kind' for invocant of type 'Any'. Did you mean any of these?
    end
    min
    sink

  in sub MAIN at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/sources/6B7E37732E0EF47675FA1A326FBA22DF7F918ADA (Documentable::CLI) line 264
  in sub RUN-MAIN at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/sources/6B7E37732E0EF47675FA1A326FBA22DF7F918ADA (Documentable::CLI) line 21
  in block <unit> at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/resources/2C55D2C0FE856AAD2A335F51AD33D66AFBC169E4 line 3
  in sub MAIN at /home/jmerelo/.rakudobrew/bin/../versions/moar-2019.07.1/install/share/perl6/site/bin/documentable line 3
  in block <unit> at /home/jmerelo/.rakudobrew/bin/../versions/moar-2019.07.1/install/share/perl6/site/bin/documentable line 1

Also, it would be better if errors were caught and indicated where they actually occur.

Not clear syntax is exhaustive. For instance, "do" as a prefix and other statement prefixes are not in the "language" area.

(Item from a TODO list made by @JJ. I need this one needs a separate issue to discuss the problem because I do not fully understand it.)

It's actually not happening now, but it could happen, like here.

Describe the bug
Binary file "documentable" is missing a short version of option '--version'. I recommend it be '-V' as other programs use when '-v' is already used.

To Reproduce
Run

$ docmentable -h

and see the current list of options. A short version of '--version' is absent.

Describe the bug

$ documentable update
Checking for changes...
Source verified
Got cache at ./.cache-doc
Caching language/mop
Cache fully updated
1 file(s) modified. Starting regeneratiion ...

Extra "i" in regeneratiion

They work correctly, but in the tests I have set them badly, so they print useless information when you run the tests. Also, 'documentable -V' is always executed and it should not.

Pod::To::Cached (a dependency of this module) has failures, so I cannot install Documentable.

finanalyst/pod-cached#25

If you run documentable outside the root directory, it returns:

Checking for changes...
Source verification failed with:
doc is not a directory
  in submethod TWEAK at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/sources/D8380CC32DB7035B76CD2282A9EF7BCE5986F884 (Pod::To::Cached) line 180
  in sub MAIN at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/sources/2D9DBDEC1292D3B5D1A752CD491B5232A0322942 (Perl6::Documentable::CLI) line 207
  in sub RUN-MAIN at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/sources/2D9DBDEC1292D3B5D1A752CD491B5232A0322942 (Perl6::Documentable::CLI) line 21
  in block <unit> at /home/jmerelo/.rakudobrew/versions/moar-2019.07.1/install/share/perl6/site/resources/37E70165280CF8465DA5E204F97C6395054B9837 line 3
  in sub MAIN at /home/jmerelo/.rakudobrew/bin/../versions/moar-2019.07.1/install/share/perl6/site/bin/documentable line 3
  in block <unit> at /home/jmerelo/.rakudobrew/bin/../versions/moar-2019.07.1/install/share/perl6/site/bin/documentable line 1

Capturing the error and saying exactly what happens (it does not find the doc directory) might be a better option.

To make bug reports easier, for instance...

You can't apparently run documentable start after documentable update. It hangs when generating source files at 0.25%

A but has already been raised in Pod::To::Cached, but it might be workaround-able here.

Related to #9 , we need to make sure it works correctly on all platforms.

This document is not rendered properly, so it's unreadable. It would be interesting to generate that in the gh-pages, which also look positively ugly.

Describe the bug

With master branch, in the top-level repo dir running:

prove6 -Ilib -v
Test Summary Report
-------------------
t/102-update.t  (Wstat: 0 Tests: 2 Failed: 0)
  Parse errors: Got line Documentable version: (not found) after late plan
t/103-highlight.t  (Wstat: 0 Tests: 1 Failed: 0)
  Parse errors: Got line Documentable version: (not found) after late plan
Files=19, Tests=96,  14 wallclock secs
Result: FAILED

I discovered the failure when trying to install. I got a test failure but am not sure what caused it, so I ran the manual test and got the results above.

OS: Debian 10 (Buster), 64-bit
Perl 6: This is Rakudo Star version 2019.03.1 built on MoarVM version 2019.03
implementing Perl 6.d.

This is related to #5 , but also to the fact that there's no way to specify an alternate place for templates, they are slurped from the documentable location...

Weird fragments are generated in some cases, for instance here. These also produce an HTML error, as shown below

Also, that header is indexed also in the h1 tag, so it does not make a lot of sense to index it twice.

Is your feature request related to a problem? Please describe.
A partial build failure was caused by a bad file in the default cache.

Describe the solution you'd like
Provide the following commands or something similar for documentable:

1. remove a specific file from the cache
2. clean the cache

Note I solved my immediate problem by manually removing the bad-file's entry in the cache.
However, it looks like maybe there could be some kind of .cache-ignore file which would be handy in such circumstances.

Templates use now ad hoc variables. It's not clear if new variables could be added, and how to deal with them. Change to a real templating engine, which would deal with all new variables in a principled way.

They should get moved to the new one and tagged with the new release. As a matter of fact, since we can obtain the release from $*RESOURCES we should probably get the right version for that thing.
This is related to #33

Document variables in templates, which ones are there, and how they should be used.

To acommadte Raku/doc#2535

As seen in Raku/doc#2986

Describe the bug
Go to the doc repo top-level directory and run:

$ documentable setup

After the command finishes, the following files are NOT found:

Makefile
app-start
app.pl

To Reproduce
Clone and install the HEAD of the master branch of module Documentable.

Run the command as shown in the problem step.

Expected behavior
To find the reported missing files in the doc repo at the top-level.

Desktop (please complete the following information):

• OS: Debian 10 (Buster)
• Documentable version: 1.0.9
• Perl 6 version: This is Rakudo Star version 2019.03.1 built on MoarVM version 2019.03
  implementing Perl 6.d

Additional context
My clones of repos Documentable and doc are in separate directories.

Some thoughts I have from initially playing with documentable in a fork of the doc repo:

• I would put the default config.json in a config-default directory.
• I would have the user put his config.json in a config-user directory (to be read-only for documentable after setup).
• I would prefer you to use the JSON::Hjson module for reading and writing the configuration files to minimize human error when modifying the config file.
• The default operation for generating the pages within a section is not clear since I can't see the new look, but it should be an alpha sort on the first visible title within each section.
• I would ensure there is some way to allow the user to generate a default config file with his own sections and one or more skeleton files. One HUGE advantage of Hjson is the ability to embed comments.
• It would be helpful to show the docs (written in Pod6) on-line as Markdown files for on-line rendering. Perhaps manually running Pod::To::Markdown on the when changed. Then reference those files in the Github IO pages.

Transferred from antoniogamiz/Perl6-Documentable#54.

This might be related to #16, and it's definitely related to this error in pod-cached finanalyst/pod-cached#18

To Reproduce

Remove a file from the fileset

Expected behavior

It should simple remove it from the cache

Screenshots

This is the last version of Documentable and Pod::To::Cached, but it probably happens all across versions.

Right now it just hangs up (and makes the fan start whirring). It would be more convenient if something was shown, a spinning wheel or a progress bar or something.

TODO:

Add emojis to progress messages
Check if there are modules for progress bar
Improve time display (problem with last item display)

As you may have seen, the short text below each index and subindex page is hardcoded. Those texts are not general and some users may want to change them so I will add and additional "description" key to the configuration file to specify them.

Change Perl 6 instances to Raku.