Add instructions to test production build

[MatteoRobbiati]

After a discussion with @Edoardo-Pedicillo, I modified the url references into the navbars, in order to correctly compute the docs' pages once the site is built (in my case with yarn build) and opened from the out folder which is created through (yarn next export).

After this modification the pages are correctly showed in built mode but the error occurs in development mode. I'm trying to understand the reason of this.

I suggest to wait for the merge, if we plan to be able to show all the site in development mode from the master branch.

[alecandido]

Wait, is it working without the .html in dev mode?

For me, the one online is also working without .html (i.e. without this PR), I believe for you too, and that is generated by the workflow exactly with yarn build && yarn next export.

Are you sure that this is not an XY problem?

[MatteoRobbiati]

Wait, is it working without the .html in dev mode?

yes.

For me, the one online is also working without .html (i.e. without this PR), I believe for you too, and that is generated by the workflow exactly with yarn build && yarn next export.

In this case it doesn't work for me.

Are you sure that this is not an XY problem?

Can you define XY problem?

[alecandido]

Can you define XY problem?

https://xyproblem.info/

[alecandido]

In this case it doesn't work for me.

Is this page working for you? https://qibogang.github.io/docs/qibo/last I mean: can you see it Qibo docs just clicking on the link? Not building on your machine, just looking the online version built by GitHub

[MatteoRobbiati]

In this case it doesn't work for me.

Is this page working for you? https://qibogang.github.io/docs/qibo/last I mean: can you see it Qibo docs just clicking on the link? Not building on your machine, just looking the online version built by GitHub

Yes, it works. It is stil in the rtd form but it works.

[alecandido]

It is stil in the rtd form but it works.

Yes, because the iframe is pointing to the rtd site, that is still using the rtd theme.

[alecandido]

Then the problem is a local one, no problem actually in production. Try to run:

git clean -fdx

To see if removing generated files, and building from scratch, the problem is solved.

[alecandido]

I guess it is a problem with Python http.server module (I guess you are using that one for testing, I told either you or @Edoardo-Pedicillo at some point).

Try with:

# from inside the `out` folder
npx http-server ./

Instead of npx (coming with npm). I used pnpx (coming with pnpm), of course ;D There is no yarn equivalent, but you can use --yarn flag: https://stackoverflow.com/a/66612901/8653979

[alecandido]

I believe the main problem to be that Python http.server is serving files, and make an exception only for index.html and index.htm https://docs.python.org/3/library/http.server.html?highlight=http%20server#http.server.SimpleHTTPRequestHandler.do_GET

You don't see the problem with other pages, only because the navigation is hijacked by Next.js Link component. E.g. if you just start the server, and then visit http://localhost:8000/tutorials/ you will see that is not serving the page (the one you would obtain with the same URL if clicking on the "Tutorials" link from the home page).

So, it was not really an XY problem, but just a workaround, about a poor simple HTTP server being used for testing. I'm using it all the time, but it is important to know the limitations (luckily GitHub is using something better for Pages xD but Python docs themselves warn against usage in production, see https://docs.python.org/3/library/http.server.html "Warning" at the top of the page).

[MatteoRobbiati]

Thank you @AleCandido for the explanations.

[alecandido]

Thank you @AleCandido for the explanations.

Sooner or later, write a brief comment about this in the README, for future reference (other people running the site, and having the same issue).

However, I've been silly: don't you use http-server, Next has one built in:

yarn build
yarn start

You don't even need to export, it uses the production build inside the .next folder. https://github.com/qibogang/qibogang.github.io/blob/ab236b2199c2ca12b278bb108ed9e5416860c88d/package.json#L8 But first you have to build!

Use this PR to do it: revert the .html change (you can also use git revert <commit-hash>), then add info to the README.

[MatteoRobbiati]

After the previous discussion, I reverted the urls commit and added some instructions related to the static HTTP server in the README.md