Contribution documentation

[kottkrig]

Hi 👋

I'm coming from hexpm/hexpm#659 and was thinking that I'd make an attempt at fixing the referenced bug.

However – I'm stumbling a bit in getting ex_doc running locally so that I can debug the less and js code. Are there any contribution docs somewhere to get a newcomer up and running?

The README.md seems to only contain instructions on how to run ex_doc in the context of a project but I can't find any information on how to run it in the context of contributing.

The instructions in ./assets/README.md are nice and clear but they fail to mention how I can test my changes in a browser locally.

[josevalim]

@kottkrig one of the ways is to clone ex_doc to your machine, go to your project and specify ex_doc as a path dependency. Something like:

{:ex_doc, path: "../relative/path/to/ex_doc"}

Would that work?

[kottkrig]

@josevalim I added ex_doc as a path dependency to a local project but the generated doc files don't include my changes to the ex_doc/assets/*.less files.

These are the steps I've taken to get my changes to show up:

1. Clone ex_doc project
2. Add ex_doc as a path dependency to project_a
3. Run gulp watch in ex_doc/assets directory
4. Make changes to app.less (which triggers the gulp script to generate new css files)
5. Run mix docs in project_a

I've also tried running gulp build instead of watch but neither of them seems to work.

Is this the intended workflow?

[josevalim]

Oh, I see! After you change the assets you need to: 1. Run “npm run script” 2. Run “mix compile” 3. Run mix deps.compile ex_doc in the parent project -- *José Valimwww.plataformatec.com.br <http://www.plataformatec.com.br/>Founder and Director of R&D*

[kottkrig]

I must be doing more things wrong. 😊

The generated files in project_a/doc/ are still not using my css files. I'm now doing:

1. Clone ex_doc project
2. Add ex_doc as a path dependency to project_a
3. Make changes to app.less
4. Run npm run build in ex_doc directory
5. Run mix compile in ex_doc directory
6. Run mix deps.compile ex_doc in project_a directory
7. Run mix docs in project_a directory

[josevalim]

Just to be double sure, let's try this:

• step 4 as is
• run mix compile --force in step 5
• remove _build as the step 6
• proceed with step 7

[kottkrig]

Thanks! That worked wonders!

So to test every change I will need to run the steps 4-7?

[josevalim]

You may be able to skip step 6 and 7.

[kottkrig]

Bummer! Skipping step 6 and 7 didn't work for me.

Oh well. At least now I know how to get it running. Thanks for you patience @josevalim! 👍

[wojtekmach]

@kottkrig we can also test css/js changes on the ex_doc itself, so it can be:

0. git clone git@github.com:elixir-lang/ex_doc.git && cd ex_doc
1. mix deps.get && npm install
2. npm run build && mix compile --force && mix docs && open doc/index.html

in fact, we can probably have two aliases for it

• mix setup for step 1 (Combine all setup steps into mix setup hexpm/hexpm#649)
• mix check for step 2 (looking for a better name)

wdyt @josevalim?

[kottkrig]

@wojtekmach that worked great. Thanks for the tip!

Out of curiousity: What's the current use case for gulp watch?

[nscyclone]

@wojtekmach setup sounds like a good idea but I suppose that there is not much sense to create the check alias. There is already a compile step in the docs task (but without the --force flag yet), probably it's better to simply extend docs with the npm run build call?

[wojtekmach]

@nscyclone good point, instead of adding new task we can alias docs to do that 👍