search

fable-compiler / fable-graphics

Fable bindings for graphic tools: D3, DC, Three, Pixi
https://fable-compiler.github.io/fable-graphics/
Apache License 2.0
23 stars 8 forks source link

[WIP] Not ready : Feature/docs #2

Closed MangelMaxime closed 8 years ago

MangelMaxime commented 8 years ago

Here is what I am thinking about adding samples + documentation on this repo. First, the docs folder is for all the repo (not only for pixi in our case).

Repo structure

I have been testing severals structure for the repo and here is the last one I have push on this PR:

  1. Have all the bindings in the bindings directory
  2. Docs, is for all the repo
  3. Have samples in the samples directory. Use subdirectory to group by binding (currently not reflected by the files)

    Docs structure

For the moment it's still pretty rough.

Target is to have an index page which present the repo with the different bindings. Add a link, in each bindings section to the samples page for this binding.

Of course, these are just suggestions.

Questions

Should we follow the strucutre of virtual-dom where each samples are independants ? Or try to do something like @whitetigle did in his repo ?

First solutions can lead to have Severals time the same assets. The second solutions, is less flexible I think.

Personaly I would go for the first one.

@alfonsogarciacaro For the moment, the docs.fsx file is working like the one from virtual-dom.

I have two problems:

  1. I need to put the samples directly at the root of the samples forlder. I have samples/basic and I would like samples/pixi/basic.
  2. I don't understand how to make the sample interactive.

Please, could you help me with this ?

Edit part to track todos:

whitetigle commented 8 years ago

Should we follow the strucutre of virtual-dom where each samples are independants ? Or try to do something like @whitetigle did in his repo ?

We have 35+ samples. So what's at stake if we go solution 1?

MangelMaxime commented 8 years ago

We will just have one directory by samples.

For the moment the, all the samples are really simple (no offense here). Most of them are one file sample I think. But what will happened if we got a bigger sample.

One of my idea when I was testing the architecturewas to have files.fsx in order to references the files to build just like we do in the electron samples. My concerns with that is how to link the files with F# Formatting for the doc generation.

And I think this could be best for the new people to be able to pick one sample repo and play with it. Compare to the need of understanding a more complex architecture.

MangelMaxime commented 8 years ago

Another question that I have is the following:

The idea here is @whitetigle seems to want to make sure we don't have breaking change etc. And I am ok with that. So those should be made by tests and not by samples.

Probably we should make proper samples as I have describe a couple of example. Perhaps some unique example made to show the power of having F# for Pixi.

And have most of the code made by @whitetigle in the test repo. And have the same architecture that he have.

whitetigle commented 8 years ago

And I think this could be best for the new people to be able to pick one sample repo and play with it. Compare to the need of understanding a more complex architecture.

100% agreed.

So those should be made by tests and not by samples

Yes, that would be better. One way could be to send values to JS and get results from F# to check that results are the same as expected. I have not dug yet into unit testing in F#. We would use NUnit for that?

Probably we should make proper samples as I have describe a couple of example. Perhaps some unique example made to show the power of having F# for Pixi.

That would be great indeed!

And have most of the code made by @whitetigle in the test repo. And have the same architecture that he have.

I don't know if we need to keep this architecture. But what is important I think would be able to allow users to compare F# samples against JS samples and see how they behave. That was one of the goals after all of porting the samples. What I would like to do would be to show code side by side on the same page by loading both JS and F#. So maybe we could have a special single page F# VS JS that would allow us to do that. So we would end up with some complex samples with explanations and this page as a neat little tool for fast checking?

Should the samples be based on the package.json version ? Or the development version from the repo.

IMO package so that what the user reads is what happens. Then for more experienced users, I think they won't have problems to change the path of the bindings and make tests according to their needs. And since we'll have tests done, I think that we will have only very few gaps between npm and git.

MangelMaxime commented 8 years ago

So if I summarize.

[...] pick one sample repo and play with it.

  • Use package.json to code the samples. And in dev we will switch manually when working on the sample.
  • Have a comparaison side by side for F# vs JS. For this point, I think that can be good to do it on some sample but not all. Because after people will tend to port the code from JS to F# vs try to write it with F#. (Hope that make sense).
  • For the tests I didn't understand. How do you want to make Unit Test on graphical libraries ?
whitetigle commented 8 years ago

For this point, I think that can be good to do it on some sample but not all

Well since I already load the F# code from the .fsx file, I can load the JS code from the .js file as well, so that anyway there's nothing to do since it's automatic. So if it works for one sample it will work for every one :)

For the tests I didn't understand. How do you want to make Unit Test on graphical libraries ?

The mere fact that false == 0 == null == undefined does say a lot about all the errors we can get regarding type checking. JS does not always tell that something's wrong since you can pass many kind of different values and they might be accepted, no questions asked.

So I wondered about fact checking some things with unit tests. For instance make variable live through several iterations and see what happens and check our results. Initialize things in different fashions and check that we don't get undefined. Test in an empirical fashion and from time to time add a little test. Things like that. Maybe it's out of scope there? I don't know.

[EDIT] But maybe it would indeed be more testing, than Unit testing :wink:

MangelMaxime commented 8 years ago

:+1: For considering testing over Unit testing :)

alfonsogarciacaro commented 8 years ago

TBH, Tomas Petricek created the docs build script for Fable so I don't know all it's inner works but the basics are explained in this issue.

I'll try to explain more or less how I publish the samples for Fable's website. It's probably not the best way to do it but it may be helpful:

  1. I usually republish the docs with a new release of fable-compiler. I have a FAKE target to automatically update the requirements of the samples to be sure I and all the users will compile the samples with the proper version of fable-compiler and fable-core.
  2. When I run build GenerateDocs all samples get compiled. I don't have any specific unit tests for the samples yet but if the compilation of any of the samples fails, the build won't finish so I'm forced to fixed the error. Also, after all tests are compiled I use build BrowseDocs to run a local server and (manually) quickly check that samples are working correctly.

If you want, you can merge this PR and I can try to create the page for one of the samples (tell me which one you'd like to start with) and then we can use it as a template for the others. I also don't think it's very important to have the F# and the JS source side by side for the moment, we can leave that for when the REPL is ready. Users interested can always check the JS code with the browser debugger tools anyways 😄

MangelMaxime commented 8 years ago

Ok @alfonsogarciacaro . I will try to make the documentation work so. I want to be able to set up it because it's always useful :)

And so your are not against the new architecture for the repo ?

Repo structure

I have been testing severals structure for the repo and here is the last one I have push on this PR:

Have all the bindings in the bindings directory
Docs, is for all the repo
Have samples in the samples directory. Use subdirectory to group by binding (currently not reflected by the files)
alfonsogarciacaro commented 8 years ago

That's fine for me :+1:

MangelMaxime commented 8 years ago

Rah finally got one example to work. :)

whitetigle commented 8 years ago

@MangelMaxime when you need me, please tell me. Currently, I'm finishing to port the samples to test/update the bindings.

[EDIT]: I'm done with the samples. So just ping when you want me to add samples in the samples directory or if I can help you with anything.

MangelMaxime commented 8 years ago

@whitetigle Sorry to make you wait. It take more times than I was thinking to make working all the samples :). You can keep on eye on the progress via the Todo on the first message :).

If you want you can start by porting your sample with the news "structure" describe here: https://github.com/fable-compiler/fable-graphics/wiki/How-to-create-a-sample-%3F

There is actually one sample ported in the feature/docs branch. Also you can see others samples from Fable or Fable-VirtualDom to see how to write the documentation in a literal way if your need to explain the code.

My next step now is to make the output path configurable.

[Edit]: You can't for the moment have two sample names the "same ways". For now, samples/pixi/basic/basic/ is the same as samples/pixi/demos/basic. Because the script output to the files to the last using the last directory name. That's why I am working on the custom output now.

whitetigle commented 8 years ago

Sorry to make you wait. It take more times than I was thinking to make working all the samples

No problem at all! Take your time :+1:

If you want you can start by porting your sample with the news "structure" describe here:

Ok let's try!

Bon courage :)

MangelMaxime commented 8 years ago

Wiki updated with instruction about the custom output.

@whitetigle Are you working on the port of your samples ? Just to know who do what ? :)

whitetigle commented 8 years ago

@MangelMaxime Sorry. Had some unplanned task to do yesterday afternoon. So haven't done anything yet! But I can take some time today to try to port one of my sample.

MangelMaxime commented 8 years ago

@whitetigle No problem :)

I will port all the basic samples from your repo. To structure the documentation along with it.

After that we should be able to push this branch in master and add the missing samples when ready. And pushing this branch in master will allow us to release the npmjs package.

whitetigle commented 8 years ago

@MangelMaxime :laughing: you're too fast! I just started!

So I just added a sample and generated the doc and updated the bindings so it compiles. Now I'm under the main page of the samples docs. Since no index.html gets copied to the sample dir what's the strategy?

Anyway adding a sample to your system was indeed a very simple task! Very productive workflow indeed. Bravo :+1:

whitetigle commented 8 years ago

So I added a simple index.output.html with relevant paths that was copied to my sample output folder in docs and renamed it. The sample is working well. Now of course I miss styling.

MangelMaxime commented 8 years ago

@whitetigle Oh sorry I let you go with the samples. Just ping me when ready :)

For the output links, I forget to tel where to place them for the moment.

In the file docs/source/index.md you can look at line 29 to see how you can link your sample to the index.html file of the docs.

whitetigle commented 8 years ago

@alfonsogarciacaro Would you have some templating system to write the index.html files in your samples or do you write plain html. For instance for the Mario sample, did you wrote by hand all the html?

Same question for you F# snippets. I see the css but do you have some script to transform the code into html?

Thanks!

whitetigle commented 8 years ago

@MangelMaxime How many samples do you want me to port?

Sample section : For starters, I think we could go with 5-10 interesting so we make a bit tour of most common features and this will add some content until we add the first real sample/tutorial

test section I will put the remaining ones in a test folder as said earlier. Do you want a single page or a dir for each sample?

MangelMaxime commented 8 years ago

@whitetigle

Sample section : For starters, I think we could go with 5-10 interesting so we make a bit tour of most common features and this will add some content until we add the first real sample/tutorial

It's fine for me 5-10 interesting. I late you choose the ones because I don't know well pixi yet :)

test section I will put the remaining ones in a test folder as said earlier. Do you want a single page or a dir for each sample?

We could go with something like your repo. And have a single file .fsx which load all the others. Like so, we run fable againt the this single file and it's will compile all the tests.

For example, here the files.fsx is used as an entry point for Fable.

With this single file, we could have an index.html file like you have you to choose which sample to display. Don't need the javascript or fsharp snippet here. Just a select box to change the samples would be Ok I think.

For instance for the Mario sample, did you wrote by hand all the html? Not sure what you are asking but the sample are build using docs/template/sample.html as a template file.

Same question for you F# snippets. I see the css but do you have some script to transform the code into html?

This job is done by F# Formatting. This what we are using to generate the documentation with custom overhead to use Liquid as the template engine.

Hope to answer your questions :)

MangelMaxime commented 8 years ago

@whitetigle I think I understand your problem.

I mess up a merge and so the template is not good for the moment. I will fix in it and keep you inform.

MangelMaxime commented 8 years ago

@whitetigle

I just fixed the template in this branch. Can you please try to pull again and generate the docs. Now if you open the file output\index.html file you have a link to pixi basic sample and this one should have the sample running in it + the snippets.

whitetigle commented 8 years ago

Ok just pulled the changes but I get a compilation error :

Updating static pages
Processing markdown file: compatibility.md
Running build failed.
Error:
System.IO.FileNotFoundException: Impossible de charger le fichier ou l'assembly 'FSharp.Compiler.Service, Version=2.0.0.3, Culture=neutral, PublicKeyToken=null' ou une de ses dépendances. Le fichier spécifié est introuvable.
Nom de fichier : 'FSharp.Compiler.Service, Version=2.0.0.3, Culture=neutral, PublicKeyToken=null'
   à FSharp.CodeFormat.CodeFormatAgent..ctor()
   à FSharp.Literate.Literate.parsingContext[a](FSharpOption`1 formatAgent, FSharpOption`1 evaluator, FSharpOption`1 compilerOptions, FSharpOption`1 definedSymbols) dans c:\Tomas\Public\tpetricek\FSharp.Formatting\src\FSharp.Literate\Main.fs:ligne 35
   à FSharp.Literate.Literate.ParseMarkdownFile[b](String path, FSharpOption`1 formatAgent, FSharpOption`1 compilerOptions, FSharpOption`1 definedSymbols, FSharpOption`1 references, FSharpOption`1 fsiEvaluator) dans c:\Tomas\Public\tpetricek\FSharp.Formatting\src\FSharp.Literate\Main.fs:ligne 85
   à FSharp.Literate.Literate.ProcessMarkdown(String input, FSharpOption`1 templateFile, FSharpOption`1 output, FSharpOption`1 format, FSharpOption`1 formatAgent, FSharpOption`1 prefix, FSharpOption`1 compilerOptions, FSharpOption`1 lineNumbers, FSharpOption`1 references, FSharpOption`1 replacements, FSharpOption`1 includeSource, FSharpOption`1 layoutRoots, FSharpOption`1 generateAnchors, FSharpOption`1 assemblyReferences, FSharpOption`1 customizeDocument) dans c:\Tomas\Public\tpetricek\FSharp.Formatting\src\FSharp.Literate\Main.fs:ligne 153
   à FSI_0005.Docs.processMarkdown@123.Invoke(String source, String outdir)
   à FSI_0005.Helpers.processDirectory(Boolean force, String indir, String outdir, IEnumerable`1 exts, FSharpFunc`2 func)
   à FSI_0005.Helpers.processDirectory(Boolean force, String indir, String outdir, IEnumerable`1 exts, FSharpFunc`2 func)
   à FSI_0005.Docs.processMarkdown(String siteRoot, Boolean force)
   à FSI_0005.Docs.generateStaticPages(String siteRoot, Boolean force, Unit unitVar2)
   à FSI_0005.Docs.clo@360-2.Invoke(Unit _arg2)
   à Fake.TargetHelper.runSingleTarget(TargetTemplate`1 target) dans C:\code\fake\src\app\FakeLib\TargetHelper.fs:ligne 492

AVT : la journalisation de liaison d'assembly est désactivée.
Pour activer la journalisation des échecs de liaison d'assembly, attribuez la valeur 1 à la valeur de Registre [HKLM\Software\Microsoft\Fusion!EnableLog] (DWORD).
Remarque : une certaine perte de performance est associée à l'enregistrement dans le journal des échecs de liaison d'assembly.
Pour désactiver cette fonctionnalité, supprimez la valeur de Registre [HKLM\Software\Microsoft\Fusion!EnableLog].

---------------------------------------------------------------------
Build Time Report
---------------------------------------------------------------------
Target      Duration
------      --------
CleanDocs   00:00:00.0164412
Total:      00:00:06.6716092
Status:     Failure
---------------------------------------------------------------------
  1) System.IO.FileNotFoundException: Impossible de charger le fichier ou l'assembly 'FSharp.Compiler.Service, Version=2.0.0.3, Culture=neutral, PublicKeyToken=null' ou une de ses dépendances. Le fichier spécifié est introuvable.
Nom de fichier : 'FSharp.Compiler.Service, Version=2.0.0.3, Culture=neutral, PublicKeyToken=null'
   à FSharp.CodeFormat.CodeFormatAgent..ctor()
   à FSharp.Literate.Literate.parsingContext[a](FSharpOption`1 formatAgent, FSharpOption`1 evaluator, FSharpOption`1 compilerOptions, FSharpOption`1 definedSymbols) dans c:\Tomas\Public\tpetricek\FSharp.Formatting\src\FSharp.Literate\Main.fs:ligne 35
   à FSharp.Literate.Literate.ParseMarkdownFile[b](String path, FSharpOption`1 formatAgent, FSharpOption`1 compilerOptions, FSharpOption`1 definedSymbols, FSharpOption`1 references, FSharpOption`1 fsiEvaluator) dans c:\Tomas\Public\tpetricek\FSharp.Formatting\src\FSharp.Literate\Main.fs:ligne 85
   à FSharp.Literate.Literate.ProcessMarkdown(String input, FSharpOption`1 templateFile, FSharpOption`1 output, FSharpOption`1 format, FSharpOption`1 formatAgent, FSharpOption`1 prefix, FSharpOption`1 compilerOptions, FSharpOption`1 lineNumbers, FSharpOption`1 references, FSharpOption`1 replacements, FSharpOption`1 includeSource, FSharpOption`1 layoutRoots, FSharpOption`1 generateAnchors, FSharpOption`1 assemblyReferences, FSharpOption`1 customizeDocument) dans c:\Tomas\Public\tpetricek\FSharp.Formatting\src\FSharp.Literate\Main.fs:ligne 153
   à FSI_0005.Docs.processMarkdown@123.Invoke(String source, String outdir)
   à FSI_0005.Helpers.processDirectory(Boolean force, String indir, String outdir, IEnumerable`1 exts, FSharpFunc`2 func)
   à FSI_0005.Helpers.processDirectory(Boolean force, String indir, String outdir, IEnumerable`1 exts, FSharpFunc`2 func)
   à FSI_0005.Docs.processMarkdown(String siteRoot, Boolean force)
   à FSI_0005.Docs.generateStaticPages(String siteRoot, Boolean force, Unit unitVar2)
   à FSI_0005.Docs.clo@360-2.Invoke(Unit _arg2)
   à Fake.TargetHelper.runSingleTarget(TargetTemplate`1 target) dans C:\code\fake\src\app\FakeLib\TargetHelper.fs:ligne 492

AVT : la journalisation de liaison d'assembly est désactivée.
Pour activer la journalisation des échecs de liaison d'assembly, attribuez la valeur 1 à la valeur de Registre [HKLM\Software\Microsoft\Fusion!EnableLog] (DWORD).
Remarque : une certaine perte de performance est associée à l'enregistrement dans le journal des échecs de liaison d'assembly.
Pour désactiver cette fonctionnalité, supprimez la valeur de Registre [HKLM\Software\Microsoft\Fusion!EnableLog].

---------------------------------------------------------------------

Running build failed.
Error:
System.Exception: Generating documentation failed
   à FSI_0005.Build.clo@73-7.Invoke(Unit _arg6)
   à Fake.TargetHelper.runSingleTarget(TargetTemplate`1 target) dans C:\code\fake\src\app\FakeLib\TargetHelper.fs:ligne 492
MangelMaxime commented 8 years ago

@alfonsogarciacaro Could you please help on this error ?

I never understand thus errors :disappointed:

whitetigle commented 8 years ago

C:\code\fake\src\app\FakeLib\TargetHelper.fs

I don't have such a folder. So somewhere there's an absolute path set. I'll try to find it.

[EDIT] Ok so found it. Don't know what to do though :wink: 

./packages/docs/FAKE/tools/FakeLib.dll
./packages/docs/FAKE/tools/FakeLib.pdb
./packages/docs/FAKE/tools/FakeLib.pdb.srcsrv
./packages/FAKE/tools/FakeLib.dll
./packages/FAKE/tools/FakeLib.pdb
./packages/FAKE/tools/FakeLib.pdb.srcsrv
MangelMaxime commented 8 years ago

@whitetigle

I now remember having an error like that before and Alphonso said to fix the FSharp.Formatting dependency version.

Can you please make sure the paket.dependencies files is like this one:

source https://www.nuget.org/api/v2
nuget FAKE
nuget FSharp.Core

group Docs
  source https://www.nuget.org/api/v2

  nuget FAKE
  nuget Suave
  nuget DotLiquid
  nuget FSharp.Formatting 2.14.4

And perhaps try to delete the paket.lock file and your packages/ folder in order to force paket to reevaluated the dependencies tree. Otherwise, I don't really know..

Do you have the same problem if you try to generate the documentation from Fable-virtualdom ? I used this repo as example for the docs generation.

whitetigle commented 8 years ago

paket.dependencies was the same. I deleted paket.lock and rewrote it. paket.lock is now:

NUGET
  remote: https://www.nuget.org/api/v2
    FAKE (4.37.2)
    FSharp.Core (4.0.0.1)

GROUP Docs
NUGET
  remote: https://www.nuget.org/api/v2
    DotLiquid (2.0.26)
    FAKE (4.37.2)
    FSharp.Compiler.Service (2.0.0.6)
    FSharp.Core (4.0.0.1)
    FSharp.Formatting (2.14.4)
      FSharp.Compiler.Service (2.0.0.6)
      FSharpVSPowerTools.Core (>= 2.3 < 2.4)
    FSharpVSPowerTools.Core (2.3)
      FSharp.Compiler.Service (>= 2.0.0.3)
    Suave (1.1.3)
      FSharp.Core (>= 3.1.2.5)

Compilation success. Though I don't know why... Anyway, like planned I added 8 more samples which seem relevant to me with their assets. So now I need to test if I get the samples running as expected.

whitetigle commented 8 years ago

OK, every sample displays fine but 2. I have to investigate why. But It should not be a serious issue.

whitetigle commented 8 years ago

OK, I'm done with the samples. I've commited everything. Do you want me to push the changes? Do you think it would possible to rebuild the doc for one sample only when needed?

[EDIT] I will add the single page sample selector a little bit later.

MangelMaxime commented 8 years ago

Yes please push the change.

Do you think it would possible to rebuild the doc for one sample only when needed?

Yes this is possible normally, we should have the BrowseTarget in Fake which allow us to start a webserver and have auto refresh and build when one sample change (build is only for this sample). I need to check if this is still working or if I need to patch it.

whitetigle commented 8 years ago

Push done!

Yes this is possible normally, we should have the BrowseTarget in Fake which allow us to start a webserver and have auto refresh and build when one sample change (build is only for this sample). I need to check if this is still working or if I need to patch it.

Super! It would be great to allow for fast patching!

MangelMaxime commented 8 years ago

I just tested all your samples @whitetigle

Really nice job :)

@alfonsogarciacaro I just bumped the package.json version for the binding because we need to update the bindings on npmjs.com (new locations).

For me the documentation is good. We could keep working on it after publishing it.

The next steps and final steps could be:

  1. Check the samples
  2. Update the bindings on npmjs
  3. Update the reference in the samples to use the binding from the package.json + reference from #load
  4. Accept this PR
  5. Publish the docs

@alfonsogarciacaro Can you do the point 1 and 2 at least ? Because we don't have access to all the bindings and I have never publish a package too. I need to look for info on it.

And do or give your go to do the steps 3, 4 and 5. :)

Edit: Could be nice if you could do the docs just to make sure everything is ok as you have some experience on it with fable-compiler. And check if I didn't make a mistake by setting up the reference of the PublishDocs target.

MangelMaxime commented 8 years ago

@whitetigle For your point about

Do you think it would possible to rebuild the doc for one sample only when needed?

I created an issue because I will not have the time to fix it now and it's need requested to accept this PR. It's partially working but don't recompile the sample js.

whitetigle commented 8 years ago

Hi! That's great to have this documentation! Bravo! :tada:

I created an issue because I will not have the time to fix it now and it's need requested to accept this PR. It's partially working but don't recompile the sample js.

Ok.

Just so you know, I have created a new special sample for Fable that deals with some visual candies: masks, filters, and simple animations. So I will prepare a special tutorial page for this.

WIP: fable

alfonsogarciacaro commented 8 years ago

Fantastic job, thanks a lot! 🎉 I fixed the doc generation (BrowseDocs is still failing though) and published the site: https://fable-compiler.github.io/fable-graphics/

It's also easier now to build the samples standalone, check: https://github.com/fable-compiler/fable-graphics/tree/master/samples

Thanks again for this amazing contribution! 👏

whitetigle commented 8 years ago

It's also easier now to build the samples standalone, check: https://github.com/fable-compiler/fable-graphics/tree/master/samples

Excellent! Thanks!