Website does not show lists properly

[kripken]

For example, right under The optimization level you should use depends mostly on the current stage of development: on the optimizing code page we have this bulleted list:

- When first porting code, run *emcc* on your code using the default settings (without optimization). Check that your code works and :ref:`debug <Debugging>` and fix any issues before continuing.
- Build with lower optimization levels during development for a shorter compile/test iteration cycle (``-O0`` or ``-O1``).
- Build with ``-O2`` to get a well-optimized build.
[..]

However, it does not show up as a list. I just see a paragraph for each of those. That is, there are no bullet points and the items are not indented by those bullet point markers (that should exist but do not).

I see this on both Firefox and Chrome, so it doesn't seem to be a browser issue. I also see that the HTML seems fine:

<ul class="simple">
<li><p>When first porting code, run <em>emcc</em> on your code using the default settings (without optimization). Check that your code works and <a class="reference internal" href="[../porting/Debugging.html#debugging](http://localhost:8000/build/html/docs/porting/Debugging.html#debugging)"><span class="std std-ref">debug</span></a> and fix any issues before continuing.</p></li>
<li><p>Build with lower optimization levels during development for a shorter compile/test iteration cycle (<code class="docutils literal notranslate"><span class="pre">-O0</span></code> or <code class="docutils literal notranslate"><span class="pre">-O1</span></code>).</p></li>
<li><p>Build with <code class="docutils literal notranslate"><span class="pre">-O2</span></code> to get a well-optimized build.</p></li>
<li><p>Building with <code class="docutils literal notranslate"><span class="pre">-O3</span></code> or <code class="docutils literal notranslate"><span class="pre">-Os</span></code> can produce an ever better build than <code class="docutils literal notranslate"><span class="pre">-O2</span></code>, and are worth considering for release builds. <code class="docutils literal notranslate"><span class="pre">-O3</span></code> builds are even more optimized than <code class="docutils literal notranslate"><span class="pre">-O2</span></code>, but at the cost of significantly longer compilation time and potentially larger code size. <code class="docutils literal notranslate"><span class="pre">-Os</span></code> is similar in increasing compile times, but focuses on reducing code size while doing additional optimization. It’s worth trying these different optimization options to see what works best for your application.</p></li>
<li><p>Other optimizations are discussed in the following sections.</p></li>
</ul>

Using the devtools inspector I found we have list-style: none enabled in our CSS for some reason. Removing that "fixes" the issue, but then I see ugly unstyled dots for the bullet points, and they are not properly indented, so clearly that's not the right fix (which would be far beyond my CSS skills).

[adam4235]

I'd be willing to attempt this, though I also don't have CSS skills, but I'd be willing to research and learn them. I did notice that the bullet points are shown correctly when you Preview the file in github:
https://github.com/emscripten-core/emscripten/blob/main/site/source/docs/optimizing/Optimizing-Code.rst

And I found the css file that seems to be applying that style here:
https://github.com/emscripten-core/emscripten/blob/main/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css

I'm wondering though if that's a style that Emscripten has actually created? It looks like maybe it came from the Read The Docs software (it mentions the Sphinx theme from that software), and if there's an intentional reason for it?

[kripken]

Good questions. From the history it looks like it appeared all at once 10 years ago, so I'd guess it was imported from a standard css file that maybe sphinx emits when one creates a new project? But I'm not sure.

I think we can edit it to fix and improve things, or even replace it altogether if there is a better alternative. That is, there is no strong reason to keep using it right now, except that it exists and (mostly) works.

If you can improve it that would be great, @adam4235 ! All options are open from my perspective: fixing it or replacing it, and we are not tied to the current look in any way.

[adam4235]

It's looking like I might not have time for this for now after all, so someone else can feel free to take it.

[Shweta-S18]

@kripken
I’ve noticed that the list items are displayed in a paragraph format rather than as bullet points. Is this the issue we’re addressing?
Also, could you please tell me the name of the file where this code is located?”

[kripken]

@Shweta-S18

I’ve noticed that the list items are displayed in a paragraph format rather than as bullet points. Is this the issue we’re addressing?

Yes. Those should be bullet points.

Also, could you please tell me the name of the file where this code is located?

The source code for the file I gave as an example is here:

https://raw.githubusercontent.com/emscripten-core/emscripten/main/site/source/docs/optimizing/Optimizing-Code.rst

The CSS files are, I think, here:

https://github.com/emscripten-core/emscripten/tree/main/site/source/_themes/emscripten_sphinx_rtd_theme/static/css

[Shweta-S18]

@kripken
when we do list-style: disc , it suddenly page look like this hence we change it.
li.toctree-13 > a { display: none; } addition to it we applied this too .toctree-13 { display: none; }
As evident from the context,

[Shweta-S18]

@kripken
Issue: Bullet Points Not Visible:
I found that

elements have property {list-style: none} which hides the bullet points.
To make the bullet points visible, changed the value to list-style: disc.
element having the class .toctree-13.
.toctree-l3 > a { display: none; }, I suggest please add this too .toctree-13 { display: none}

[Shweta-S18]

@kripten,
I have identified an issue related to bullet points not being visible, and I have successfully resolved it by checking in the browser and making necessary changes. Could you kindly provide instructions for setting up this project locally so that I can make the necessary file changes and test it in a local browser environment? Although I reviewed the provided documentation for installation, I am still unable to proceed. As a beginner, I would greatly appreciate your guidance on the setup process.

Thank you for your valuable support! 🙌

[kripken]

Sounds promising! That could be exactly the fix we need.

To test locally, you can go to site/ in an emscripten checkout and run make html. That requires the proper version of sphinx installed, see the pip3 command mention here: https://github.com/emscripten-core/emscripten/blob/main/docs/process.md#updating-the-emscriptenorg-website

After that you can view the website by running a local webserver, like python3 -m http.server and then go to http://localhost:8000/build/html/.

[lorsanta]

This seems to be fixed now, I guess we can close this issue.