Development notes

TODO

Improve the docs

lib/Test2/Tools/Compare.pm

[ ] Add subheadings for each method
[ ] Add to the ADVANCED synopsis with more useful stuff
[ ] Make the 'import' policy easier to understand
[ ] Show how to import everything easily

lib/Test2.pm

[ ] Add SYNOPSIS after NAME & DESCRIPTION
    - See L<Test2::Suite>
    - or perhaps just move the GETTING STARTED section up and rewrite:
        If you just want to write tests for your code then go to Test2::Suite first.
        If you are interested in writing new tools for the Test2 framework you should take a look at Test2::API.
[ ] Add link to https://test-more.github.io/Test2-Suite
[ ] Summarise the INCLUDED TOOLS section from Test2::Suite
[ ] Bypass the stupid Test2::V0 namespace
[ ] Add: Much of the rest of the documentation has been written for /people developing Test2 itself/.
[ ] Actually link the NAMESPACE LAYOUT sections
[ ] Include *all* the namespaces
[ ] Move most stuff under a DEVELOPMENT subheading

lib/Test2/*.pm

[ ] Start the POD with info for testers, then with developer info following

lib/Test2/Bundle.pm

[ ] Prominent link to L<Test2::Suite>, which lists the bundles and when/why/how you would use them

General

[ ] Make the difference between Test2::Foo and Test2::Tools::Foo much clearer
    see someone making same point in 2017! https://perl-test2.slack.com/archives/C208D1JG0/p1495564527313877

For the PR:

[ ] Include all these points above
[ ] Say: I can explain how every edit I have made makes the docs easier to use.

Docs site

https://test-more.github.io/Test2-Suite/#tools-tools

This was used at a conference. It could be valuable as a more flexible format of intro.

[ ] What are tools?

    - Tools are the name Test2 uses for functions like `is()` 
        In Test2, Tools are functions that produce testing events.

    What is a "testing event"?
    - Events are generated whenever you make an assertions, set a plan, or produce diagnostics.
    - So... what are they??

    Where can I find tools?
        - Under the Test2::Tools::* namespace.
        - Note that the Test2::* modules are the internal representations, don't use these directly.
        - To import the tools, do XXXXXXX V0 etc


[ ] Add 'bag' and other stuff

Case study

Test2 documentation could do with some improvement.

How to view POD

vi

Easy to edit, not so easy to view.
I don't want to mess around with vim plugins, or even mdless

Perldoc

Easy to use, but extremely lacking in features, like links... Even man has links!

POD renderers

So. Many. Options.

Pod::Browser - Uses Catalyst
Pod::Server - ?
Pod::Webserver - Basic
- Lots of dependencies, Catalyst, etc
- Parses better than Pod::POM::Web
- Shows built-in modules by default, but they can be filtered out
- How to run: podwebserver
Pod::POM::Web - Advanced design
- Fails to parse nested tags
- Shows built-in modules by default, but they can probably be filtered out
- How to run: perl -I $DOC_PATH -I $POD_POM_WEB_PATH -MPod::POM::Web -e server
Pod::Simple::HTMLBatch - The best one?
- Properly marked up HTML, so fully customisable with CSS.
- Split into top-level directories.
- Doesn't do .t files, but can use a subclass of Pod::Simple::Search rigged to recognise .t files. Submitted patch.
Pod::Server - Basic default output, one single list. Docs lacking. What about CSS?

Questions / Discussion

What is the reference implementation of a POD interpreter? perldoc just removes links and it is plain text only. So in what viewer do the links actually link to something? I don't think there is a good standard for viewing darkpan code locally. But the MetaCPAN has a wonderful interface for modules that are on CPAN.

MetaCPAN

MetaCPAN viewed through a web browser is actually the very best POD viewer. Although I can imagine a better one, it's already quite good. The menu links that can be moved out of the way are absolutely ideal. It can even be stuck to the top of the page with some trivial CSS.

Since POD is viewed most often on MetaCPAN, why not test documentation changes directly on that rendering system?

You will need at minimum metacpan-web, probably metacpan-api as well. But it may be easier to use metacpan-docker.

Development notes

Jump to

Quick reference

Improving Perl's Test2 documentation and using the metacpan docker image

TODO

Improve the docs

Docs site

Case study

How to view POD

vi

Perldoc

POD renderers

Questions / Discussion

MetaCPAN

Folding@Home FAHClient on Mac OSX

Search this blog

Highlights

Quick reference

Links

Blog Archive

Tags

	# Failing to get the metacpan docker image to work on Mac OSX 13.6 High Sierra.

	# Note: Docker specifically says my version of Mac OSX is not supported: https://docs.docker.com/desktop/mac/install/

	Mac [12:35 alt$] git clone https://github.com/metacpan/metacpan-docker.git
	Cloning into 'metacpan-docker'...
	remote: Enumerating objects: 643, done.
	remote: Counting objects: 100% (31/31), done.
	remote: Compressing objects: 100% (27/27), done.
	remote: Total 643 (delta 6), reused 18 (delta 2), pack-reused 612
	Receiving objects: 100% (643/643), 173.82 KiB \| 903.00 KiB/s, done.
	Resolving deltas: 100% (281/281), done.
	Mac [12:35 alt$] cd metacpan-docker
	autoenv:
	autoenv: WARNING:
	autoenv: This is the first time you are about to source /Users/will/alt/metacpan-docker/.env:
	autoenv:
	autoenv: --- (begin contents) ---------------------------------------
	autoenv: COMPOSE_PROJECT_NAME=metacpan$
	autoenv: PLACK_ENV=development$
	autoenv: PGDB=pgdb:5432$
	autoenv: API_SERVER=morbo -l http://*:5000 -w app.psgi -w bin -w lib -w templates --verbose$
	autoenv:
	autoenv: --- (end contents) -----------------------------------------
	autoenv:
	autoenv: Are you sure you want to allow this? (y/N) y
	-bash: -l: command not found
	Mac [12:35 master metacpan-docker$] PGDB="pgdb:5432$"
	Mac [12:36 master metacpan-docker$] API_SERVER="morbo -l 'http://*:5000' -w app.psgi -w bin -w lib -w templates --verbose bin/api.pl"
	Mac [12:36 master metacpan-docker$] bin/metacpan-docker init
	Initializing metacpan-docker repositories:
	Cloning into 'metacpan-api'...
	remote: Enumerating objects: 20087, done.
	remote: Counting objects: 100% (449/449), done.
	remote: Compressing objects: 100% (267/267), done.
	remote: Total 20087 (delta 166), reused 410 (delta 156), pack-reused 19638
	Receiving objects: 100% (20087/20087), 5.24 MiB \| 1.75 MiB/s, done.
	Resolving deltas: 100% (11426/11426), done.
	Repository metacpan-api ready.
	Cloning into 'metacpan-web'...

Development notes

Jump to

Quick reference

Improving Perl's Test2 documentation and using the metacpan docker image

TODO

Improve the docs

Docs site

Case study

How to view POD

vi

Perldoc

POD renderers

Questions / Discussion

MetaCPAN

Folding@Home FAHClient on Mac OSX

Search this blog

Highlights

Quick reference

Links

Blog Archive

Subscribe To

Tags