Add inchci to project

Questions / Help
, ,
#1

Background

I have a small project that I want to document. Now, documentation is nice and all, but I also want others to know that documentation matters to me, so I want to add a badge to my readme.

Badges

To do this, I am trying to use inchci.org. After adding my project I am greeted with the following page:

Screenshot 2020-07-23 at 15.14.56
Screenshot 2020-07-23 at 15.14.561191×425 31 KB

Which tells me to run the following command:

MIX_ENV=docs mix do deps.get, inchci.add

Now, this doesn’t work because I don’t have a config/docs configuration file. Not only do I not have one, I also have no idea what to put in it if I create it.

Questions

  • What am I doing wrong?
  • Do I really need a config/docs configuration file? What do I put in it?
  • How do I add inchci to my project ?
  • Do I also need to add it to the pipeline so it runs every time I make a change?
#2

Use the :dev env.

Usage of the :docs env was a pattern years ago.

#3

NobbZ is right but for completeness sake I wanted to answer your question about the config/docs-file nonethess:

Do I really need a config/docs configuration file? What do I put in it?

The reason you “need” one is that your config/config.exs file contains the following line:

import_config "#{Mix.env()}.exs"

When you now execute MIX_ENV=docs mix do deps.get, inchci.add this will evaluate to import_config "docs.exs" which is the file you don’t have.

In theory you could wrap this call with something like (but I don’t recommend to do this):

if File.exists?("#{__DIR__}/#{Mix.env()}.exs") do
  import_config "#{Mix.env()}.exs"
else
  IO.warn("No config file for env '#{Mix.env()}' found.")
end

The easier (and arguably cleaner) solution would be to create a (nearly) empty config/docs.exs:

use Mix.Config
2 Likes
#4

Thanks for the explanation guys, but now I get another error:

The task “inchci.add” could not be found

I am quite confused. Has any of you ever tried using this?

#5

In which environment did you execute inchci.add and how did you install inch_ex?

I assume you copied the suggested line from the docs, right?

{:inch_ex, ">= 0.0.0", only: :docs}

And that you now executed mix inchci.add without MIX_ENV, right?

In that case it can not find inchci.add because the dependency is only installed in the docs env. Try to replace only: :docs with only: :dev.

Or dont. InchEx 2.0 does not support inchci.add (yet). You get this error message when you try:

This feature is not supported in Inch 2.0 (yet).

But inch_ex also hasn’t been updated in a while so I guess no luck?

#6

So, it is impossible to get a documentation badge for my project, right?

I thought of making a PR, but then I also saw there are 23 PR done without a response from @rrrene . Perhaps I am missing something?

Are there any other documentation tools you guys know of I could use?

#7

The most recent version of inch_ex doesn’t have the generator for inch-ci, you still might be able to set things up manually. But thats just guessing.

Also you can try to use ~> 1.0 and hope that it is compatible with the version of elixir you are using in your project.

Only of both options have been tested and ruled out, then you can say its impossible.

1 Like
#8 
Unfortunately, InchEx 1.x does not support Elixir version above 1.6.x, since the documentation format has changed with Elixir 1.7.0.

If you want to try Inch with Elixir >= v1.7.0, just set the Inch dep to

    {:inch_ex, github: "rrrene/inch_ex"}

** (CaseClauseError) no case clause matching: :ok
    lib/mix/tasks/inchci_add.ex:28: Mix.Tasks.Inchci.Add.add_to_inch_ci/0
    (mix 1.10.3) lib/mix/task.ex:330: Mix.Task.run_task/3
    (mix 1.10.3) lib/mix/cli.ex:82: Mix.CLI.run_task/2
    (elixir 1.10.3) lib/code.ex:926: Code.require_file/2

One option is out. If I set the dependency version to {:inch_ex, github: "rrrene/inch_ex"} it then gives me the error mentioned above.

This feature is not supported in Inch 2.0 (yet).

Just out of curiosity, would you be kind enough to elaborate?
What approach would you have in mind?

#9

That all sounds too complicated to me. Only you can judge whether documentation is good or not, 3rd parties, even good ones, cannot. To show you care, simply go to https://naereen.github.io/badges/ create the badge of your choice and link it to your hexdocs page.

That’s it.

Generic badge

2 Likes
#10

That’s rather dismissive. You’re right that anybody can add any badge they want but that doesn’t invalidate OPs desire to use a service such as InchCI.

I think the idea behind inch is quite interesting, especially because it doesn’t try to rate documentation in the classic sense but instead give transparency where documentation is present and to which degree.

I recommend to take a look at this talk from René, the author of Inch:

1 Like
#11

It might be, but it’s the solution that works right now, unlike the advice to listen to [very good, btw, I attended this CBLite] talk about the service that does not work right now.

#12

Although I will admit I quite like the badge, I have to say I dont see a purpose in using such a badge.

The purpose of badges (for me at least) is to convey information in a quick and visible way. When you visit a project and the “build badge” is red, it likely means the project is in trouble and you probably should avoid it because the master branch is not passing the basic pipeline.

If you visit a project and see 80% of its code is documented you know 2 things:

  • documentation is important and is being considered
  • it is going to be easier for you to contribute to the project because you have more information available

This is why I believe in InchCI and why I don’t just put a random badge in the project. Saying I made the docs with love is nice, but ultimately it conveys no useful information to others.

It is a shame InchCI is not working. Does any of you know any other alternatives?

1 Like
#13

Of course, it’s entirely up to you, but I could not disagree more. To me, the badge “docs made with :heart:” says two things:

  • documentation is important and is being considered
  • it is going to be easier for you to contribute to the project because you have more information available

while “80% of its code is documented” in Elixir land means the documentation is very poor. Also, docs are usually 1-click from the place where this badge is usually located, and anyone can click and see how good the documentation is immediately.

Putting this badge requires effort, while empty @doc false everywhere, generated by IDE, would make any tool happily confirming 100% coverage.

1 Like