Implement header in Sphinx

[galuhsahid]

As discussed in #51, we need a separate PR to implement header. I think we probably need to determine what the value should be, though, whether we should stick to panda's implementation or not (& if not what the value of header should be).

[datapythonista]

For a bit of extra information...

In pandas the standard is to assume in all docs that pandas and numpy are already imported (as pd and np). I really hate the practices (both importing implicitly and using aliases), but that has been like this for years, and the rest of the maintainers prefer not to change it.

Since every file in the docs had those imports, and few things more, we ended up standardizing it in a variable, so when something changes, it changes everywhere.

[Aya-S]

@galuhsahid can you provide some more details about this issue and may be an entry point to tackle this?

[galuhsahid]

@Aya-S Sure! When I tried to build the docs I saw these undefined {{ header }} variables in all of the pages, which happens because we haven't yet initialized the header variable in our current setup of the docs.

I think a good entry point would be to replicate what pandas is doing and see if it works, then if it does maybe we can iterate from there should we want to change something. The content of the header variable in pandas can be found here--it's a bunch of import statements and the reason why they're there, I'm guessing, is what @datapythonista said.

Seems like we also need to set these up too:
https://github.com/pandas-dev/pandas/blob/master/doc/source/conf.py#L330
https://github.com/pandas-dev/pandas/blob/master/doc/source/conf.py#L695

[MKhalusova]

Is anyone working on this? If not, I can give it a go.

[MKhalusova]

I guess no one is, I'll take it then.

[Aya-S]

@MKhalusova I was planning to work on it but fell ill and am still recovering. you can go ahead and attempt this.

[MKhalusova]

For a bit of extra information...

In pandas the standard is to assume in all docs that pandas and numpy are already imported (as pd and np). I really hate the practices (both importing implicitly and using aliases), but that has been like this for years, and the rest of the maintainers prefer not to change it.

Since every file in the docs had those imports, and few things more, we ended up standardizing it in a variable, so when something changes, it changes everywhere.

Why do docs need to import pandas and numpy?

[datapythonista]

Not the right person to answer that, since I think it's a very bad idea, and I'm strongly against doing that. But some people in the core dev team want to avoid having an import pandas at the beginning of examples, since it's supposed to be obvious by readers.

[MKhalusova]

@datapythonista Sorry, that's not what I meant. Let me rephrase. Generated documentation is in HTML, so what purpose does an added import serve in an html file?
So here for instance https://pandas.pydata.org/pandas-docs/stable/development/contributing.html
I don't see it in the resulting html.
Having import would make sense if the resulting "thing" was executable, that's the source of my confusion

[datapythonista]

Ah, I understand now, good point.

I don't think in the contributing documentation there is much code, but in the user guide for example there are lots of ipython block codes that sphinx runs to show the output in the html pages.

[MKhalusova]

I've had some circumstances that prevent me from completing this. Someone else can take over.

[martinagvilas]

I could give it a try if this is still relevant.

[datapythonista]

I proposed yesterday to remove it from pandas (pandas-dev/pandas#28038), but I'd say it's a good learning exercise, and relevant in the short term.